WOW Extensions Functions and Messages

Functions


About WOW Extensions

Thank you for purchasing WOW Extensions, Liant Software's programming tool that allows you to design and develop event-driven Windows applications completely in COBOL. It allows you, the developer, to implement a full-featured graphical user interface to your RM/COBOL application, while retaining the COBOL business logic and data access.

About This Document

The documentation for WOW Extensions is available in two HTML Help files:

· WOW Functions and Messages Help (cblwowfm.chm). This help file contains comprehensive information about Windows messages, Windows API functions, and WOW functions (including those that support ActiveX, RPC, and Thin Client implementations). It also includes lists of the functions and messages, arranged alphabetically, with links to the complete descriptions.

· WOW Designer Help (cblwow.chm). This is the primary help file, providing you with online documentation for the WOW Extensions Designer, including reference information about the key elements of the Designer window, descriptions of the commands on the menus, dialog boxes, tools in the Toolbox, buttons on the toolbar, and how to work with WOW Extensions projects. It also provides an alphabetic reference for each of the intrinsic (standard) Windows and the ActiveX controls used in the WOW Extensions development environment. Properties and events are defined for each control, along with a discussion of the properties and events used by forms. For quick reference, this help file contains a checklist summarizing whether the properties for a specific control or form can be manipulated with the WOW Designer at design time, retrieved or set at runtime, or both.

The WOW Designer Help file also contains the enhancements to this version and to earlier releases of WOW Extensions. See the “What’s New in WOW Extensions” topic. For instructions on using the Help system, see “Using WOW Extensions Help.”

Technical Support

Liant Software offers various support options. For a complete list and a description of each, visit the Product Support section at the Liant web site: http://www.liant.com.

You may also use any of the following methods to contact Liant Software Corporation.

E-mail | sales@liant.com
Telephone | US | (1) 512-343-1010 (1) 800-762-6265 (800-RM-COBOL)
Fax | US | (1) 512-343-9487
Mail | Liant Software Corporation 5914 West Courtyard Drive, Suite 100 Austin, Texas 78730 USA

Copyright 1995-2008. Liant Software Corporation. All rights reserved.


Functions

Using Functions in WOW Extensions

ActiveX Functions

Thin Client Functions

RPC Functions

WOW Functions

Windows API Functions

Character Functions

Class Functions

Device Context/GDI Functions

Dialog Functions

Font Functions

Menu Functions

Profile Functions

Scroll Bar Functions

System Functions

Window Functions


Using Functions in WOW Extensions

See Also

The term “function” is a term commonly associated with C-language programming. In WOW Extensions, functions are non-COBOL routines (or subprograms) that allow you to use the capabilities of the Windows operating system. To COBOL applications, functions are non-COBOL callable subprograms. Because most documentation on Windows will refer to these subprograms as functions, that term is used here.

Functions allow you to adjust the initial state of the forms and controls that you create in the WOW Designer. A function executes code that can be used to carry out a specific task.

WOW Extensions supports the following types of functions:

· Windows API Functions

· WOW Functions, including the following:

-  ActiveX Functions

-  RPC Functions

-  Thin Client Functions

Most of the functions that you will use are in the Windows API (Application Programming Interface) category. Other functions are specifically designed for ActiveX controls and to address issues exclusive to WOW Extensions.

Note The Windows API functions that are part of WOW Extensions are virtually identical to the functions used with C-language programming. Books or magazines that discuss using the Windows API and are oriented to C-language programming will also give you insight on using API functions with WOW Extensions.

When you call a function, you are actually calling a function in the WOW Extensions runtime module. Most functions require you to specify parameters. If the function is a Windows API function, WOW Extensions translates the parameters and then calls the Windows function. Because this translation is extremely efficient, there is no performance penalty.

WOW Extensions provides code templates for frequently-used function calls so that it is easier to understand what the parameters are for a particular function. The available templates are listed in the Code Templates tree on the WOW Designer window.

For more information on using functions in WOW Extensions, click one of the following topics:

· How functions are called

· How functions return values

· How functions are implemented

· Returning a function value in your own data item

· Functions with more than one action

· Using literals as function parameters

· Window and ActiveX control handle parameters

· Functions with multiple parameter types

· Two special WOW functions


How Functions Are Called

You call Windows API and WOW functions (including ActiveX, RPC, and Thin Client functions) in the same manner as you call a COBOL program. The following example illustrates a call to a Windows API function that releases control of the mouse cursor. This function is relatively simple and does not require any parameters.

CALL RELEASECAPTURE.

Most functions, however, require you to specify one or more parameters. These parameters are passed using the COBOL USING clause on the CALL statement. The following example calls the Windows API function, CLOSEWINDOW, to minimize a window and passes a window handle to the called function to identify the window to be closed.

CALL CLOSEWINDOW USING WND-H.

The WND-H field, which contains a valid window handle, must be numeric (at least ten digits in size). It can be any type of numeric field.

Note WOW Extensions will validate the required number of digits and report an error if an invalid field is passed as a parameter.


How Functions Return Values

Many functions return a value to indicate the result of the function. The following example illustrates a call to a Windows API function that destroys a window and then returns a value to indicate the success or failure of the function.

CALL DESTROYWINDOW USING WIN-RETURN WND-H.

The first parameter usually returns the value. If the function is successful, the return value is nonzero (1). If the function is unsuccessful, the return value is zero (0). This type of return value is common with Windows API functions. These values correspond to the WIN-TRUE and WIN-FALSE values defined in the copy file windows.cpy, which interfaces COBOL with the Windows API functions.

WIN-RETURN is a generic return field declared in windows.cpy. This copy file must be included in your application if you use any WOW functions. It contains the declarations of the functions and many other fields that will be useful in using Windows.


How Functions are Implemented

See Also

WOW Extensions makes it easy to interface with Windows API functions. The function entry points and parameters must be translated from COBOL to C-language conventions and data types. WOW Extensions allows you to code as if you had called the functions directly. Additionally, all the translation to your COBOL code is performed transparently.


Returning a Function Value in Your Own Data Item

In some cases, you will want to use your own field to store the return value of functions, especially those that create forms, menus, or other windows. The following example creates a menu. The return value is a handle to the menu.

CALL CREATEMENU USING MENU-H.

In this case, MENU-H may be any type of numeric field.


Functions with More than One Action

Some functions produce different results depending on the parameters passed. The following examples illustrate such results. The first example enables a window for user input; the second example disables the window.

Example 1

CALL ENABLEWINDOW USING WIN-RETURN WND-H WIN-TRUE.

Example 2

CALL ENABLEWINDOW USING WIN-RETURN WND-H WIN-FALSE.

WIN-TRUE and WIN-FALSE are standard values declared in windows.cpy. Many functions will use WIN-TRUE or WIN-FALSE in this manner. It is helpful to remember the following C-language programming convention when using Windows: WIN-TRUE equals 1, and WIN-FALSE equals 0.


Using Literals as Function Parameters

See Also

Numeric and alphanumeric literals can be used as arguments to WOW functions wherever a numeric or alphanumeric data item could be used, with the exception of handles. Since handles must be returned by Windows, WOW Extensions will reject a numeric literal if it is passed as a handle.

The following two examples are equivalent:

Example 1

01 MIN-VALUE PIC 9(8) VALUE 10.
01 MAX-VALUE PIC 9(8) VALUE 2000.

CALL SETSCROLLRANGE USING SB-H SB-CTL MIN-VALUE
MAX-VALUE WIN-TRUE.

Example 2

CALL SETSCROLLRANGE USING SB-H SB-CTL 10 2000 WIN-TRUE.

These two examples are also comparable:

Example 1

01 NEW-TEXT PIC X(40) VALUE "Text for Window".

CALL WOWSETPROP USING WIN-RETURN WNDORACTIVEX-H "TEXT" NEW-TEXT.

Example 2

CALL WOWSETPROP USING WIN-RETURN WNDORACTIVEX-H "TEXT"
"TEXT FOR WINDOW".


Window and ActiveX Control Handle Parameters

See Also

Handles are identifiers, created and returned by Windows, which uniquely identify a window (that is, the forms and controls). A handle is unique for the entire operating system, not just within the application. Standard (intrinsic) window handles generated by the WOW Designer (for forms and intrinsic controls) are numeric values with ten digits. ActiveX control handles generated by the WOW Designer are eight-byte alphanumeric fields. If you declare your own standard (intrinsic) window handle, it must be at least PIC 9(10) BINARY(4).

Window Handle Example

01 WND-H PIC 9(10) BINARY(8).

CALL WOWSETPROP USING WIN-RETURN WNDORACTIVEX-H "Caption"
"New Caption".

ActiveX Control Handle Example

01 ACTIVEXCTL-H PIC X(8).

CALL WOWSETPROP USING WIN-RETURN ACTIVEXCTL-H "Caption"
"New Caption".


Functions with Multiple Parameter Types

Some functions will accept several data types for a single parameter. The APPENDMENU function is one such example. The last parameter passed to the APPENDMENU function may be numeric or alphanumeric, depending on how the function is used.

In this example, the last parameter is numeric and contains a bitmap handle.

01 BITMAP-H PIC 9(10) BINARY(8).

SET MF-BITMAP TO TRUE.
CALL APPENDMENU USING WIN-RETURN MENU-H MENU-FLAGS
NEWITEM-H BITMAP-H.

In this example, the last parameter is alphanumeric and contains the text of the menu option.

01 OPTION-TEXT PIC X(20).

SET MF-STRING TO TRUE.
CALL APPENDMENU USING WIN-RETURN MENU-H MENU-FLAGS
NEWITEM-H OPTION-TEXT.


Two Special WOW Functions

See Also

Most of your programming with WOW Extensions will consist of using two highly specialized WOW functions, WOWGETPROP and WOWSETPROP. These functions allow you to retrieve and set the property values of forms, intrinsic controls, and ActiveX controls during runtime.

Forms and controls have many different types of property values, including alphanumeric, numeric, true/false, and so forth, that define how they are displayed and they function in the running application. The WOWGETPROP and WOWSETPROP functions will work with any of these types of settings and provide a consistent interface to form and control properties.

These two functions can also be used to retrieve and set multiple properties of a single control with only one call.

The following example illustrates setting the text in the Caption property of a control:

CALL WOWSETPROP USING WIN-RETURN CTL-H "Caption" "New Caption".

This example shows how that text would be retrieved into a field called ALPHA-FIELD:

CALL WOWGETPROP USING WIN-RETURN CTL-H "Caption" ALPHA-FIELD.

Setting multiple properties with a single call is shown in the following example:

CALL WOWSETPROP USING WIN-RETURN CTL-H "Caption" "New Caption"
"FontName" "Courier"
"FontSize" 24
"Visible" 1.

Retrieving multiple properties with a single call is illustrated in the following example:

CALL WOWGETPROP USING WIN-RETURN CTL-H "Caption" TEXT-VALUE
"FontName" FONTNAME-VALUE
"FontSize" FONTSIZE VALUE
"Visible" VISIBLE-VALUE.


ActiveX Functions

See Also

Some ActiveX controls provide special capabilities that are invoked as methods. These methods can be thought of as functions or procedures built into the control. Other ActiveX control properties occur multiple times and are described as indexed. The following table summarizes the ActiveX functions. (Note that the ActiveX functions fall under the general category of WOW functions to distinguish them from Windows API functions.)

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
AXDOMETHOD | Executes the specified method for an ActiveX control.
AXGETAXHANDLE | Returns the ActiveX handle for an ActiveX control.
AXGETCLASSID | Returns the class identifier for an ActiveX control.
AXGETGUID | Returns the Globally Unique Identifier (GUID) for an ActiveX control.
AXGETHWND | Returns the Windows handle for an ActiveX control.
AXGETINDEXPROP | Retrieves the indexed properties of ActiveX controls.
AXSETINDEXPROP | Sets the indexed properties of ActiveX controls.


AXDOMETHOD

ActiveX Control WOW Function

The AXDOMETHOD function executes the specified method for an ActiveX control. Information about methods and parameters can be found in the control's documentation. When supplying parameters to a method, you do not need to worry about the data types being used. WOW Extensions will convert the data to the proper format based on information contained in the control. Make sure that you supply the parameters in the proper order. Parameters identified by the control's documentation as optional may be omitted.

Calling Sequence

CALL AXDOMETHOD USING WIN-RETURN ACTIVEXCTL-H
METHOD-NAME PARAM… [GIVING PARAM-RESULT].

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value of the method. (See the ActiveX control's documentation for more information.)
ACTIVEXCTL-H | PIC X(8) | The handle generated for the ActiveX control by WOW Extensions.
METHOD-NAME | alphanumeric | Literal or data item containing the method name.
PARAM… | numeric | Parameters for the method. Multiple parameters can be specified.
PARAM-RESULT |  | An optional parameter to receive the value returned by the method. Note that not all methods return values. This is not the same as the WIN-RETURN parameter; PARAM-RESULT is valid only if the WIN-RETURN value is zero. This optional argument is identified by the control’s documentation and may be omitted.

Note 1 Some methods may change the content of parameters as an undocumented side-effect. Use the BY CONTENT reserved word to protect values in the calling program from such an outcome.

Example

Many controls provide an AboutBox method that will display an About Box identifying the control. This method generally requires no parameters. The AboutBox method for a control with the name MYACTIVEX would be invoked as follows:

CALL AXDOMETHOD USING WIN-RETURN MYACTIVEX-H "ABOUTBOX".

Note 2 Calling ActiveX METHODS using literals is discouraged. Liant recommends that a WORKING STORAGE variable or constant be used. For example:

WORKING-STORAGE SECTION.
78 POPConnect VALUE "Connect".
...
PROCEDURE DIVISION.
...
Call AXDoMethod Using Win-Return
POP3-H
POPConnect.


AXGETAXHANDLE

ActiveX Control WOW Function

The AXGETAXHANDLE function returns the ActiveX handle for an ActiveX control.

Calling Sequence

CALL AXGETAXHANDLE USING ACTIVEXCTL-H WND-H.

Parameter | Declaration | Description
ACTIVEXCTL-H | PIC X(8) | The handle generated for the ActiveX control by WOW Extensions.
WND-H | PIC 9(10) BINARY(8) | The Windows handle of the ActiveX control.


AXGETCLASSID

ActiveX Control WOW Function

The AXGETCLASSID function returns the class identifier for an ActiveX control.

Calling Sequence

CALL AXGETCLASSID USING WIN-RETURN ACTIVEXCTL-H CLASS-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if successful.
ACTIVEXCTL-H | PIC X(8) | The handle generated for the ActiveX control by WOW Extensions.
CLASS-ID | PIC X(n) where n is a number large enough to hold the requested item. | The class identifier string of the ActiveX control.


AXGETGUID

ActiveX Control WOW Function

The AXGETGUID function returns the Globally Unique Identifier (GUID) for an ActiveX control.

Calling Sequence

CALL AXGETGUID USING WIN-RETURN ACTIVEXCTL-H GUID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if successful.
ACTIVEXCTL-H | PIC X(8) | The handle generated for the ActiveX control by WOW Extensions.
GUID | PIC X(n) where n is a number large enough to hold the requested item. | The GUID of the ActiveX control.


AXGETHWND

ActiveX Control WOW Function

The AXGETHWND function returns the Windows handle for an ActiveX control.

Calling Sequence

CALL AXGETHWND USING WND-H ACTIVEXCTL-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The Windows handle of the ActiveX control.
ACTIVEXCTL-H | PIC X(8) | The handle generated for the ActiveX control by WOW Extensions.


AXGETINDEXPROP

ActiveX Control WOW Function

The AXGETINDEXPROP function retrieves the indexed properties of ActiveX controls.

Calling Sequence

CALL AXGETINDEXPROP USING WIN-RETURN ACTIVEXCTL-H PROPERTY-NAME
PROPERTY-VALUE INDEX….

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ACTIVEXCTL-H | PIC X(8) | The handle that identifies the ActiveX control.
PROPERTY-NAME | alphanumeric | Literal or data item containing the property name.
PROPERTY-VALUE | alphanumeric or numeric | Data item that will receive the property value.
INDEX… | numeric | Literals or data items that are the index(es) for the property. Multiple indices can be specified. If more than one index is specified, the most significant index should be placed first.


AXSETINDEXPROP

ActiveX Control WOW Function

The AXSETINDEXPROP function sets the indexed properties of ActiveX controls.

Calling Sequence

CALL AXSETINDEXPROP USING WIN-RETURN ACTIVEXCTL-H PROPERTY-NAME
PROPERTY-VALUE INDEX….

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ACTIVEXCTL-H | PIC X(8) | The handle that identifies the ActiveX control.
PROPERTY-NAME | alphanumeric | Literal or data item containing the property name.
PROPERTY-VALUE | alphanumeric or numeric | Data item that will receive the property value.
INDEX… | numeric | Literals or data items that are the index(es) for the property. Multiple indices can be specified. If more than one index is specified, the most significant index should be placed first.


Thin Client Functions

See Also

These functions support the Thin Client implementation of WOW Extensions. The following table summarizes the Thin Client functions. (Note that the Thin Client functions fall under the general category of WOW functions to distinguish them from Windows API functions.)

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
REMOTEPROGRAM | Calls a non-COBOL program that resides in a user’s dynamic-link library (DLL) file. Note, however, that this function is written as WOWTHINCLIENTREMOTEPROGRAM.
SETNOWAIT | Causes the Thin Client server either to wait or not wait for each function to complete before returning to the COBOL program. Note that due to the nature of their actions, certain other functions will complete despite this function being set. Note, however, that this function is written as WOWTHINCLIENTSETNOWAIT.


REMOTEPROGRAM

Thin Client WOW Function

The REMOTEPROGRAM function calls a non-COBOL program that resides in a user’s dynamic-link library (DLL) file, passing the arguments Arg1-ArgN.

Note This function is written as WOWTHINCLIENTREMOTEPROGRAM.

Calling Sequence

CALL WOWTHINCLIENTREMOTEPROGRAM USING DLL-PATH-NAME PROGRAM-NAME
ARG1 ARG2…ARGN.

Parameter | Declaration | Description
DLL-PATH-NAME | alphanumeric | A user-created dynamic-link library file.
PROGRAM-NAME | alphanumeric | A non-COBOL program that resides in DLL-PATH-NAME on a remote client machine.
ARG1-ARGN | alphanumeric | One or more arguments to pass to and from the program that resides on the remote client machine.


SETNOWAIT

Thin Client WOW Function

The SETNOWAIT function causes the Thin Client server either to wait or not wait for each function to complete before returning to the COBOL program. Note that due to the nature of their actions, certain other functions will complete despite this function being set.

Note This function is written as WOWTHINCLIENTSETNOWAIT.

Calling Sequence

CALL WOWTHINCLIENTSETNOWAIT USING STATE.

Parameter | Declaration | Description
STATE | windows.cpy | Specifies whether the Thin Client server will wait for the function to complete. If the value of this parameter is WIN-TRUE, the function will cause the server to wait. If the value of this parameter is WIN-FALSE, the function causes the server not to wait.


RPC Functions

See Also

These functions add certain RPC (Remote Program Calls) capabilities, normally available with RPC, to the Thin Client implementation of WOW Extensions. The following table summarizes the RPC functions. (Note that the RPC functions fall under the general category of WOW functions to distinguish them from Windows API functions.)

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
GETCLIENTADDR | Allows a program in the run unit on the server to retrieve the IP address of the client.
GETCLIENTARGS | Returns command line arguments from the remote client machine.
REMOTECOMMAND | Provides the ability to execute a command on the remote system. There are two formats for the REMOTECOMMAND function. REMOTECOMMAND-1 uses individual parameters. REMOTECOMMAND-2 uses a single parameter block. REMOTECOMMAND is the code shortcut listed in the WOW Designer window. The function is written, however, as REMOTECMD.
REMOTECOPY | Provides the ability to copy files between the local and remote systems. There are two formats for the REMOTECOPY function. REMOTECOPY-1 uses individual parameters. REMOTECOPY-2 uses a single parameter block.
REMOTESHELLEXECUTE | Provides the ability to execute the Windows ShellExecute command on a remote Windows system. There are two formats for the REMOTESHELLEXECUTE function. REMOTESHELLEXECUTE-1 uses individual parameters. REMOTESHELLEXECUTE-2 uses a single parameter block.


GETCLIENTADDR

RPC WOW Function

The GETCLIENTADDR function allows a program in the run unit on the server to retrieve the IP address of the client. This function may be called by any program in the run unit and may be called more than once.

Calling Sequence

CALL GETCLIENTADDR USING IP-ADDRESS.

Parameter | Declaration | Description
IP-ADDRESS | alphanumeric | A data item having at least 15 characters.


GETCLIENTARGS

RPC WOW Function

The GETCLIENTARGS function can be executed on the server in a Thin Client architecture to retrieve any parameters that were part of the command line when the Thin Client executable (wowclient.exe) was started. It can be called only by the server portion of a Thin Client application, not the client. This function may be called by any program in the run unit on the server and may be called more than once.

Calling Sequence

CALL GETCLIENTARGS USING ARGUMENTS.

Parameter | Declaration | Description
ARGUMENTS | PIC X(255) | An alphanumeric data item of at least 255 characters.


REMOTECOMMAND

RPC WOW Function

The REMOTECOMMAND function provides the ability to execute a command on the remote system. There are two formats for the REMOTECOMMAND function. REMOTECOMMAND-1 uses individual parameters. REMOTECOMMAND-2 uses a single parameter block. REMOTECOMMAND is the code shortcut listed in the Code Templates tree area of the WOW Designer window. The function is written, however, as REMOTECMD.

Calling Sequence for Format 1

CALL REMOTECMD-1 USING REMOTE-STATUS REMOTE-SERVER
REMOTE-DIRECTORY REMOTE-COMMAND REMOTECMD-WAIT-FLAG.

Parameter

Declaration

Description

REMOTE-STATUS

PIC 9(4)

A four-digit, unsigned numeric display field that contains a value set by the function to indicate success or failure. Possible values are:

0 = Success
1 = Socket error
2 = Synchronization error
3 = Server refused request
5 = System error

REMOTE-SERVER

PIC X(80)

An alphanumeric literal or data item that contains the name or IP address of the server on which the command should be executed. In a Thin Client architecture, to execute the command on the client, this parameter should be set to spaces.

REMOTE-DIRECTORY

PIC X(128)

An alphanumeric literal or data item that contains the directory on the remote system from which the command should be executed. This provides the ability to establish a specific working directory for the command execution. It is not intended to be the path to the command itself.

REMOTE-COMMAND

PIC X(128)

An alphanumeric literal or data item that contains the command to be executed, complete with parameters, if desired.

REMOTECMD-WAIT-FLAG

PIC X

A one-byte alphanumeric literal or data item that indicates whether the control should be immediately returned to the calling program, or if RPC should wait for the completion of the command on the remote system. A value of “Y” or “y” indicates that RPC should wait for command completion. Any other value indicates that the control should be returned immediately.

Calling Sequence for Format 2

CALL REMOTECMD-2 USING REMOTECMD-WS.

REMOTECMD-WS is defined as follows (see the preceding table for parameter descriptions):

01 REMOTECMD-WS.
03 REMOTE-STATUS PIC 9(4).
03 REMOTE-SERVER PIC X(80).
03 REMOTE-DIRECTORY PIC X(128).
03 REMOTE-COMMAND PIC X(128).
03 REMOTECMD-WAIT-FLAG PIC X.


REMOTECOPY

RPC WOW Function

The REMOTECOPY function provides the ability to copy files between the local and remote systems. There are two formats for the REMOTECOPY function. REMOTECOPY-1 uses individual parameters. REMOTECOPY-2 uses a single parameter block.

Calling Sequence for Format 1

CALL REMOTECOPY-1 USING REMOTE-STATUS REMOTE-SERVER
REMOTE-LOCAL-NAME REMOTE-REMOTE-NAME REMOTE-DIRECTION
REMOTE-CRLF.

Parameter

Declaration

Description

REMOTE-STATUS

PIC 9(4)

A four-digit, unsigned numeric display field that contains a value set by the function to indicate success or failure. Possible values are:

0 = Success
1 = Socket error
2 = Synchronization error
3 = Server refused request
4 = Cannot create the local file
5 = System error
6 = Cannot write the new file
7 = Cannot open the local file
8 = Write operation failed on the remote system

REMOTE-SERVER

PIC X(80)

An alphanumeric literal or data item that contains the name or IP address of the server on which the command should be executed. To execute the command on the client in a Thin Client architecture, this parameter should be set to spaces.

REMOTE-LOCAL-NAME

PIC X(128)

An alphanumeric literal or data item that contains the name of the file on the local machine, including a path, if desired.

REMOTE-REMOTE-NAME

PIC X(128)

An alphanumeric literal or data item that contains the name of the file on the remote machine, including a path, if desired.

REMOTE-DIRECTION

PIC X

A one-byte alphanumeric literal or data item that indicates the direction of the copy operation. Two values are valid. A value of “I” or “i” indicates that the file is copied IN to the local machine. A value of “O” or “o” indicates that the file is copied OUT to the remote machine.

REMOTE-CRLF

PIC X

A one-byte alphanumeric literal or data item that indicates whether or not CRLF (carriage return/line feed) pairs should be altered based on the operating system conventions of the local and remote machines. This is helpful when copying text files. A value of “Y” or “y” indicates that CRLF characters should be modified. A value of “N” or “n” indicates that CRLF characters should not be modified.

Calling Sequence for Format 2

CALL REMOTECOPY-2 USING REMOTECOPY-WS.

REMOTECOPY-WS is defined as follows (see the preceding table for parameter descriptions):

01 REMOTECOPY-WS.
03 REMOTE-STATUS PIC 9(4).
03 REMOTE-SERVER PIC X(80).
03 REMOTE-LOCAL-NAME PIC X(128).
03 REMOTE-REMOTE-NAME PIC X(128).
03 REMOTE-DIRECTION PIC X.
03 REMOTE-CRLF PIC X.


REMOTESHELLEXECUTE

RPC WOW Function

The REMOTESHELLEXECUTE function provides the ability to execute the Windows ShellExecute command on a remote Windows system. There are two formats for the REMOTESHELLEXECUTE function. REMOTESHELLEXECUTE-1 uses individual parameters. REMOTESHELLEXECUTE-2 uses a single parameter block.

Calling Sequence for Format 1

CALL REMOTESHELLEXECUTE-1 USING REMOTE-STATUS REMOTE-SERVER
REMOTE-VERB REMOTE-FILE REMOTE-PARAMETERSS REMOTE-DIRECTORY
REMOTE-STATE REMOTE-WAIT-FLAG.

Parameter | Declaration | Description
REMOTE-STATUS | PIC 9(4) | A four-digit, unsigned numeric display field that contains a value set by the function to indicate success or failure. Possible values are: 1 = Socket error 2 = Synchronization error 3 = Server refused request 5 = System error
REMOTE-SERVER | PIC X(80) | An alphanumeric literal or data item that contains the name or IP address of the server on which the command should be executed. To execute the command on the client in a Thin Client architecture, this parameter should be set to spaces.
REMOTE-VERB | PIC X(128) | An alphanumeric literal or data item that contains the action to be performed. Common verbs are OPEN, PRINT, and EDIT. The verb must correlate with the file that is specified and the document type of the file.
REMOTE-FILE | PIC X(128) | An alphanumeric literal or data item that contains the name of the file on which the verb should be executed.
REMOTE-PARAMETERS | PIC X(128) | An alphanumeric literal or data item that specifies the command line parameters to be passed to REMOTE-FILE, if REMOTE-FILE indicates an executable.
REMOTE-DIRECTORY | PIC X(128) | An alphanumeric literal or data item that specifies the default or working directory.
REMOTE-STATE | PIC 9(4) | A four-digit, unsigned numeric field that specifies the window state. These are Windows constants, such as SW_HIDE, SW_SHOW, and so forth.
REMOTE-WAIT-FLAG | PIC X | A one-byte, alphanumeric literal or data item that indicates whether the control should be immediately returned to the calling program or whether RPC should wait for the document to be closed. A value of “Y” or “y” indicates that RPC should wait for the document to be closed. Any other value indicates that the control should be returned immediately.

Calling Sequence for Format 2

CALL REMOTESHELLEXECUTE-2 USING REMOTESHELLEXECUTE-WS.

REMOTESHELLEXECUTE-WS is defined as follows (see the preceding table for parameter descriptions):

01 REMOTESHELLEXECUTE-WS.
03 REMOTE-STATUS PIC 9(4).
03 REMOTE-SERVER PIC X(80).
03 REMOTE-VERB PIC X(128).
03 REMOTE-FILE PIC X(128).
03 REMOTE-PARAMETERS PIC X(128).
03 REMOTE-DIRECTORY PIC X(128).
03 REMOTE-STATE PIC 9(4).
03 REMOTE-WAIT-FLAG PIC X.


WOW Functions

See Also

The following table summarizes the WOW functions. (Note that ActiveX functions, RPC functions, and Thin Client functions all fall under the general category of WOW functions to distinguish them from Windows API functions.)

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function

Description

WOWADDITEM

Adds new item to a list box or combo box.

WOWADDMULTIPLESTRINGS

Adds multiple strings to the list box portion of a combo box or a list box control.

WOWCLEAR

Clears the contents of a list box or combo box.

WOWCLEARWAITCURSOR

Removes the WAIT cursor type, returns the cursor to the default shape, and sets the internal setwait cursor counter to zero. See also WOWRESETWAITCURSOR.

WOWCREATEWINDOW

Creates a window (form) that was defined using the WOW Designer.

WOWDESTROYWINDOW

Destroys the specified window (form). This function is equivalent to the Windows API DESTROYWINDOW function.

WOWDISCARDEVENTS

Clears all messages from the event queue.

WOWENDMODAL

Cancels modal behavior of one or all windows.

WOWFORMTOWOWVERSION

Retrieves a string containing the version of WOW Extension used to create a form.

WOWGETCOBOLHWND

Retrieves the handle of the RM/COBOL runtime window, which allows functions such as SETACTIVEWINDOW to be used on the RM/COBOL runtime window. The function should be a passed a handle field in order to store the window handle.

WOWGETFOCUS

Retrieves the handle of the window that currently has the input focus. This function is equivalent to the Windows API GETFOCUS function.

WOWGETFONTS

Returns a list of available font families or fonts.

WOWGETINDEXPROP

Retrieves the value of one index property for certain intrinsic controls.

WOWGETMESSAGE

Retrieves a message from the Windows message queue maintained by the WOW Extensions runtime.

WOWGETNUM

Returns the numeric value of control text, including decimal values. A return value of 1 will be returned if an invalid numeric character is contained in the field. By default, the valid characters are considered to be the digits 0 - 9, the plus (+) and minus ( - ) characters, and the edit and decimal characters (which default to comma (,) and period (.), but which can be set in the .ini file, also). This character set can be overridden by placing the following entry in the [WOWRT] section of the initialization (.ini) file:

   ValidNumericChars=0123456789$,.+-

All characters listed will be considered valid numeric characters. A limit of 80 characters is supported.

WOWGETPROP

Retrieves property values of forms and intrinsic or ActiveX controls.

WOWGETWINDOWTYPE

Retrieves the type of a control or form.

WOWGLOBALMEMORYSTATUS

Obtains information about the computer system's current usage of both physical and virtual memory.

WOWINITALLCONTROLS

Initializes all controls text or captions to their original values.

WOWINITCONTROL

Initializes a control’s text or caption to its original value.

WOWINPUTBOX

Creates, displays, and operates an input box.

WOWLOADBITMAP

Loads a bitmap image from a file and returns a handle to the bitmap that can be used with Windows API functions.

WOWLOADICON

Loads an icon from a file and creates a handle for the icon.

WOWMESSAGEBOX

Creates, displays, and operates a message-box window with the given text and title. This function is equivalent to the Windows API MESSAGEBOX function.

WOWMOVE

Moves a form or an intrinsic or ActiveX control.

WOWMULTICONTROLGETPROP

Retrieves the value of one or more properties for multiple intrinsic or ActiveX controls.

WOWMULTICONTROLSETPROP

Sets the value of one or more properties for multiple intrinsic or ActiveX controls.

WOWPEEKMESSAGE

Used to see if any messages are waiting in the message queue. If you use this function with WOWGETMESSAGE, the message loop can be placed in the middle of report printing logic, for example, to allow the report to be canceled with a Cancel button.

WOWREFRESH

Forces immediate repaint or update of an intrinsic or ActiveX control.

WOWREMOVEITEM

Removes an item from a list box or combo box.

WOWRESETWAITCURSOR

Decrements the cursor’s internal setwait cursor counter, removes the WAIT cursor type, and returns the cursor to the default shape. See also WOWCLEARWAITCURSOR and WOWSETWAITCURSOR.

WOWSETFOCUS

Assigns the input focus to a specified form or intrinsic or ActiveX control. This function is equivalent to the Windows API SETFOCUS function.

WOWSETINDEXPROP

Sets the value of one index property for certain intrinsic controls.

WOWSETNEXTCTRL

Moves input focus to the next control, based on the tab order. This function requires only WIN-RETURN as a parameter. WIN-RETURN will be set to 1 if the function succeeds and 0 if it fails. This function works only if a WOW Extensions form is active and a control on the form currently has input focus.

WOWSETNUM

Sets the text of a control or window to a representation of a number value, including decimals.

WOWSETPREVCTRL

Moves input focus to the previous control, based on the tab order. This function requires only WIN-RETURN as a parameter. WIN-RETURN will be set to 1 if the function succeeds and 0 if it fails. This function works only if a WOW Extensions form is active and a control on the form currently has input focus.

WOWSETPROP

Sets property values of forms and intrinsic or ActiveX controls.

WOWSETSTRIPTRAILING

Causes the WOW Extensions runtime either to remove (strip) or not remove trailing spaces when moving COBOL strings to and from intrinsic or ACTIVEX controls.

WOWSETWAITCURSOR

Changes the default cursor shape to the WAIT cursor type and increments an internal counter used by WOWRESETWAITCURSOR to restore the cursor to its previous shape.

WOWSTARTMODAL

Makes the specified window modal, disabling all other application windows.

WOWVERSION

Returns alphanumeric value containing version number of WOW Extensions runtime used.


WOWADDITEM

WOW Function

The WOWADDITEM function adds a new item to a list box or combo box.

WOWADDITEM places NEWITEM in the list box or combo box. If you supply a valid value for the optional INDEX, NEWITEM is placed at that position within the control. If INDEX is omitted, NEWITEM is added at the proper sorted position (if Sorted property is True), or at the end of the list (if Sorted is False).

Calling Sequence

CALL WOWADDITEM USING WIN-RETURN WND-H NEWITEM INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the list box or combo box control.
NEWITEM | alphanumeric | Data to add to the control.
INDEX | numeric | Optional, zero-based integer representing the position within the control where the new item is placed.


WOWADDMULTIPLESTRINGS

WOW Function

The WOWADDMULTIPLESTRINGS function adds multiple strings to the list box portion of a combo box or list box control.

Calling Sequence

CALL WOWADDMULTIPLESTRINGS USING WIN-RETURN WND-H COUNT
NEW-ENTRY… INDEX….

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the list box portion of a combo box or list box control.
COUNT | numeric | The number of entries in each array.
NEW-ENTRY… | alphanumeric | The string to be added. The NEW-ENTRY parameter can be repeated. For example, NEW-ENTRY [1] indicates the first element in an array of values to add to the control.
INDEX… | numeric | Literals or data items that indicate where the strings were added. Multiple indices can be specified. For example, INDEX [1] indicates the first element in an array of returned indexes indicating where the strings were added.


WOWCLEAR

WOW Function

The WOWCLEAR function clears the contents of a list box or combo box.

Calling Sequence

CALL WOWCLEAR USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the list box or combo box.


WOWCLEARWAITCURSOR

WOW Function

The WOWCLEARWAITCURSOR function removes the WAIT cursor type (an hourglass), returns the cursor to the default shape (usually a diagonal arrow), and sets the internal setwait cursor counter to zero.

WOWCLEARWAITCURSOR differs from WOWRESETWAITCURSOR in that WOWCLEARWAITCURSOR returns the cursor to the default shape immediately, regardless of the value of the internal setwait cursor counter.

Calling Sequence

CALL WOWCLEARWAITCURSOR USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.


WOWCREATEWINDOW

WOW Function

The WOWCREATEWINDOW function creates a window (form) that was defined using the WOW Designer. The child windows are created by this function at the same time as the main window.

The WOWCREATEWINDOW function is similar to the Windows API CREATEWINDOW function. The WOWCREATEWINDOW function reduces coding because it creates the child windows as well as the main window and sets many control properties. This function should be used only with window definitions generated by the WOW Designer.

Calling Sequence

CALL WOWCREATEWINDOW USING FORMNAME-H FORMNAME-DEF WIN-STYLE
PARENT-H FORMNAME-CTL-HS.

Parameter | Declaration | Description
FORMNAME-H | generated .wws file | The return value is the handle of the new window (form) if the function is successful. Otherwise, it is zero.
FORMNAME-DEF | generated .wws file | This data item is generated by the WOW Designer. It contains a description of the main window and any child windows it contains.
WIN-STYLE | windows.cpy | Specifies the style of the window being created. For details on the window styles that can be specified in this parameter, see the WIN-STYLE parameter section in the discussion of the CREATEWINDOW function.
PARENT-H | PIC 9(10) BINARY(8) | The handle of the parent or owner window of the window being created. A valid window handle must be supplied when creating a child window or an owned window. An owned window is an overlapped window that is destroyed, hidden when its owner is minimized, and that is always displayed on top of its owner window. For pop-up windows, a handle can be supplied but is not required. If the window does not have a parent window or is not owned by another window, the PARENT-H parameter must be set to zero.
FORMNAME-CTL-HS | generated .wws file | This data item is generated by the WOW Designer. It will contain the handles of each of the child windows that the main window contains.


WOWDESTROYWINDOW

WOW Function

The WOWDESTROYWINDOW function destroys the specified window (form). The function sends appropriate messages to the window to deactivate it and remove the input focus. It also destroys the window’s menu, flushes the application queue, destroys outstanding timers, removes clipboard ownership, and breaks the clipboard-viewer chain (if the window is at the top of the viewer-chain). It sends a WM-DESTROY message to the window.

If the given window is the parent of any windows, WOWDESTROYWINDOW automatically destroys these child windows when it destroys the parent window. The function destroys child windows first and then the window itself.

Applications should always call the WOWDESTROYWINDOW function to destroy their top-level windows before terminating.

If the window being destroyed is a child window and does not have the WS-EX-NOPARENTNOTIFY style set, a WM-PAINT message is sent to the parent.

This function is equivalent to the Windows API DESTROYWINDOW function.

Calling Sequence

CALL WOWDESTROYWINDOW USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be destroyed.


WOWDISCARDEVENTS

WOW Function

The WOWDISCARDEVENTS function clears all messages or events from the Windows and ActiveX event queues.

The WOWDISCARDEVENTS function can be used whenever messages or events that may have been created are not to be processed. This could occur when exiting a program that has removed all its windows, or when dismissing a dialog and beginning report processing. Use of this function is not required at any time.

Calling Sequence

CALL WOWDISCARDEVENTS USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.


WOWENDMODAL

WOW Function

The WOWENDMODAL function can be used to cancel the modal behavior of all windows (the first format) or a single window (the second format). When used to cancel the modal behavior of one window, that window must be the topmost modal window.

Calling Sequence

CALL WOWENDMODAL USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the window for which to cancel modal behavior.


WOWFORMTOWOWVERSION

WOW Function

The WOWFORMTOWOWVERSION function retrieves a string containing the version of WOW Extensions used to create a form.

Note This function is not available for WOW Thin Client.

Calling Sequence

CALL WOWFORMTOWOWVERSION USING WIN-RETURN FORMNAME-H STRING-VALUE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is 1 if the function is successful. Otherwise, it is zero.
FORMNAME-H | PIC 9(10) BINARY(8) | The handle of the form.
STRING-VALUE | alphanumeric | A string containing the WOW Extensions version.


WOWGETCOBOLHWND

WOW Function

The WOWGETCOBOLHWND function returns the handle of the RM/COBOL runtime window. This action allows functions such as SETACTIVEWINDOW to be used on the RM/COBOL runtime window.

This handle is useful for controlling window activation and display, which is particularly useful when an application uses a mixture of legacy code in the RM/COBOL window and WOW Extensions programs using their own window. By having a handle to the RM/COBOL window, the window can be activated and deactivated at appropriate times.

Calling Sequence

CALL WOWGETCOBOLHWND USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | This parameter receives the handle of the RM/COBOL runtime window.


WOWGETFOCUS

WOW Function

The WOWGETFOCUS function retrieves the handle of the window that currently has the input focus.

This function is equivalent to the Windows API GETFOCUS function.

Calling Sequence

CALL WOWGETFOCUS USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The return value is the handle of the window with input focus. If no window has the focus, the return value is zero.


WOWGETFONTS

WOW Function

The WOWGETFONTS function returns a list of available font families or fonts. The WOWGETFONTS function is similar to the Windows API functions, EnumFonts and EnumFontFamilies. Since the interface to these functions is not compatible with COBOL, WOWGETFONTS provides their functionality in a slightly different interface.

Windows provides fonts in a hierarchical format, where individual fonts are grouped into font families. To find out all the available fonts on a system, you must first find all the available font families, then find all available fonts in each family.

The CREATEIC function can be used to obtain a device context handle to use with this function.

Calling Sequence

CALL WOWGETFONTS USING WIN-RETURN DC-H FONT-FAMILY FONTS.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
DC-H | PIC 9(10) BINARY(8) | A device context handle that identifies the device for which fonts are to be listed.
FONT-FAMILY | alphanumeric | If blank, specifies that font families should be listed. If it contains a value, the value specifies the font family for which to list the available fonts.
FONTS | X(32) OCCURS nnn TIMES | Contains the names of the font families or fonts.


WOWGETINDEXPROP

WOW Function

The WOWGETINDEXPROP function retrieves the value of one index property for certain intrinsic controls, including status bar, tab, and toolbar.

Note This function is not available for WOW Thin Client.

Calling Sequence

CALL WOWGETINDEXPROP USING WIN-RETURN WND-H PROPERTY-NAME
PROPERTY-VALUE INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.
WND-H | PIC X(8) | The handle that identifies the control.
PROPERTY-NAME | alphanumeric | Literal or data item containing the property name.
PROPERTY-VALUE | alphanumeric or numeric | Data item that will receive the property value.
INDEX | numeric | Literal or data item that is the occurrence of the index for the property.


WOWGETMESSAGE

WOW Function

The WOWGETMESSAGE function retrieves a message from the Windows message queue maintained by the WOW Extensions runtime. The WOWGETMESSAGE function is central to every WOW Extensions application. The messages returned by this function drive the application processing. This function will be automatically generated in the template program created by the WOW Designer.

WIN-MSG-WS is declared in windows.cpy as follows:

01 WIN-MSG-WS GLOBAL.
02 WIN-MSG-HANDLE PIC 9(10) BINARY(8).
02 WIN-MSG-HANDLE-A REDEFINES WIN-MSG-HANDLE PIC X(8).
02 WIN-WPARAM PIC S9(10) BINARY(8).
02 WIN-WPARAM-HL REDEFINES WIN-WPARAM.
03 FILLER PIC 9 BINARY(4).
03 WIN-WPARAM-H PIC S9(5) BINARY(2).
03 WIN-WPARAM-L PIC S9(5) BINARY(2).
03 WOW-KEY-VALUE REDEFINES WIN-WPARAM-L
PIC 9(10) BINARY(2).
02 WIN-LPARAM PIC S9(10) BINARY(8).
02 WIN-LPARAM-A REDEFINES WIN-LPARAM PIC X(8).
02 WIN-LPARAM-HL REDEFINES WIN-LPARAM.
03 FILLER PIC 9 BINARY(4).
03 WIN-LPARAM-H PIC 9(5) BINARY(2).
03 WIN-LPARAM-L PIC 9(5) BINARY(2).
02 WIN-MSG-ID PIC 9(10) BINARY(8).
02 WIN-MSG-ID-RED REDEFINES WIN-MSG-ID.
03 FILLER PIC X(6).
03 WIN-MSG-ID-A PIC XX.

The information returned in each of these fields is described as follows:

Field | Description
WIN-MSG-HANDLE | The handle of the window with which the message is associated.
WIN-WPARAM-H | The meaning of the value varies depending on message.
WIN-WPARAM-L | The meaning of the value varies depending on message.
WOW-KEY-VALUE | Used in key press events (KeyUp, KeyPress, KeyUp) to retrieve the value of the pressed key.
WIN-LPARAM | The meaning of the value varies depending on message.
WIN-MSG-ID | The unique identifier of the message; for example, WM-CLOSE and EN-KILLFOCUS.

Calling Sequence

CALL WOWGETMESSAGE USING WIN-RETURN WIN-MSG-WS WM-NOTIFY-WS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function successfully retrieves a message. If an error occurs and no message is returned, the return value is zero. This should occur only if the number or size of parameters passed to the function are incorrect.
WIN-MSG-WS | windows.cpy | Contains the message information.
WM-NOTIFY-WS | windows.cpy | Returns 32-bit common control event information.


WOWGETNUM

WOW Function

The WOWGETNUM function returns the numeric value of control text, including decimal values. This function makes it easy to use edit fields for entry of numeric data by performing the conversion between numeric data and text. The same type of conversion is also applied by the WOWGETPROP and WOWSETPROP functions if a numeric parameter is supplied for an alphanumeric property.

Calling Sequence

CALL WOWGETNUM USING WIN-RETURN WND-H NUMERIC-VALUE.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is always zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that obtains the numeric value of text.
NUMERIC-VALUE | numeric | Numeric value of text.


WOWGETPROP

WOW Function

The WOWGETPROP function can be used to retrieve one or more property values from a form, or an intrinsic or ActiveX control at runtime.

The ability to retrieve multiple property values makes WOWGETPROP the preferred method for retrieving property values.

Calling Sequence

CALL WOWGETPROP USING WIN-RETURN WNDORACTIVEX-H
PROPERTY-NAME… PROPERTY-VALUE….

Parameter

Declaration

Description

WIN-RETURN

windows.cpy

The return value is always zero.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle that identifies the form, or the intrinsic or ActiveX control that retrieves property value(s).

PROPERTY-NAME…

alphanumeric

Name of property for which the value is to be retrieved. The PROPERTY-NAME parameter can be repeated.

PROPERTY-VALUE…

alphanumeric
or numeric

Data item in which to store the property value. The PROPERTY-VALUE parameter can be repeated.


WOWGETWINDOWTYPE

WOW Function

The WOWGETWINDOWTYPE function retrieves the type of a control or form.

Note This function is not available for WOW Thin Client.

Calling Sequence

CALL WOWGETWINDOWTYPE USING WIN-RETURN WND0RACTIVEX-H
WINDOWTYPETEXT WINDOWTYPETEXT-SIZE WINDOWTYPE.

Parameter

Declaration

Description

WIN-RETURN

numeric

The length of the retuned type.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle of an intrinsic or ActiveX control, or form.

WINDOWTYPETEXT

alphanumeric

A string that describes the window type.

WINDOWTYPETEXT-SIZE

numeric

The size of the WINDOWTYPETEXT field or 0.

WINDOWTYPE

windows.cpy

The type of window. Possible values are declared as 78-level descriptions under “WINDOW TYPES” in windows.cpy.


WOWGLOBALMEMORYSTATUS

WOW Function

The WOWGLOBALMEMORYSTATUS function obtains information about the computer system's current usage of both physical and virtual memory.

You can use WOWGLOBALMEMORYSTATUS to determine how much memory your application can allocate without severely affecting other applications. The information returned by this function is volatile. There is no guarantee that two sequential calls to this function will return the same information.

Calling Sequence

CALL WOWGLOBALMEMORYSTATUS USING WIN-RETURN MEMORYSTATUS-WS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
MEMORYSTATUS-WS | windows.cpy | Specifies the storage for returned memory information. This parameter can be one or more of the following values:
 | Value | Meaning
 | MS-AVAILPAGEFILE | Indicates the number of bytes available in the paging file.
 | MS-AVAILPHYS | Indicates the number of bytes of physical memory available.
 | MS-AVAILVIRTUAL | Indicates the number of bytes of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process.
 | MS-LENGTH | Not used.
 | MS-MEMORYLOAD | Percent of memory in use. Specifies a number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use.
 | MS-TOTALPAGEFILE | Indicates the total number of bytes that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk.
 | MS-TOTALPHYS | Indicates the total number of bytes of physical memory.
 | MS-TOTALVIRTUAL | Indicates the total number of bytes that can be described in the user mode portion of the virtual address space of the calling process.


WOWINITALLCONTROLS

WOW Function

The WOWINITALLCONTROLS function initializes all controls’ text or captions to their original values.

Calling Sequence

CALL WOWINITALLCONTROLS USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the form containing the controls to initialize.


WOWINITCONTROL

WOW Function

The WOWINITCONTROL function initializes a control’s text or caption to its original value.

Calling Sequence

CALL WOWINITCONTROL USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the control being initialized.


WOWINPUTBOX

WOW Function

The WOWINPUTBOX function creates, displays, and operates an input box. This function displays a prompt in a text box, waits for the user to input text or click a button, and then returns a string containing the contents of the text box.

Calling Sequence

CALL WOWINPUTBOX USING WIN-RETURN FORM-H PROMPT TITLE
TEXT XPOS YPOS WIDTH HEIGHT.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is 1 if the user presses Enter or clicks the OK button. Otherwise, it is zero.
FORM-H | PIC 9(10) BINARY(8) | The handle of the form that will own the input box. This value cannot be 0.
PROMPT | alphanumeric | Specifies the string expression displayed as the prompt message in the input box.
TITLE | alphanumeric | Specifies the string expression to be displayed in the title bar of the input box.
TEXT | numeric | Supplies the default value for text in the input box and receives input text if WIN-RETURN has a value of 1.
XPOS | numeric | Optional parameter that specifies the distance of the left edge of the input box from the left edge of the screen. If you omit XPOS, the input box is centered horizontally.
YPOS | numeric | Optional parameter that specifies the distance of the upper edge of the input box from the top of the screen. If you omit YPOS, the input box is positioned vertically approximately one-third of the way down the screen.
WIDTH | numeric | Optional parameter that indicates the width of the input box.
HEIGHT | numeric | Optional parameter that indicates the height of the input box.


WOWLOADBITMAP

WOW Function

The WOWLOADBITMAP function loads a bitmap image from a file and returns a handle to the bitmap that can then be used with Windows API functions.

When the application is finished using the bitmap, the handle should be deleted using the Windows API DELETEOBJECT function to free system resources.

Calling Sequence

CALL WOWLOADBITMAP USING BITMAP-H BITMAP-FILE.

Parameter | Declaration | Description
BITMAP-H | PIC 9(10) BINARY(8) | The return value is the handle of the bitmap.
BITMAP-FILE | alphanumeric | Specifies the name of the file containing the bitmap.


WOWLOADICON

WOW Function

The WOWLOADICON function loads an icon from a file and creates a handle for the icon.

Calling Sequence

CALL WOWLOADICON USING ICON-H ICON-FILE.

Parameter | Declaration | Description
ICON-H | PIC 9(10) BINARY(8) | The handle of the icon.
ICON-FILE | alphanumeric | Specifies the name of the file containing the icon.


WOWMESSAGEBOX

WOW Function

The WOWMESSAGEBOX function creates, displays, and operates a message-box window. The message box contains an application-defined message and title, plus any combination of the predefined icons and push buttons.

When a system-modal message box is created to indicate that the system is low on memory, the strings pointed to by the TEXT and TITLE parameters should not be taken from a resource file since an attempt to load the resource may fail.

If a message box is created while a dialog box is present, use the handle of the dialog box as the WND-H parameter. The WND-H parameter should not identify a child window, such as a control in a dialog box.

This function is equivalent to the Windows API MESSAGEBOX function.

Calling Sequence

CALL WOWMESSAGEBOX USING WIN-RETURN WND-H TEXT TITLE
MESSAGE-BOX-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if there is not enough memory to create the message box. If the function is successful, the return value is one of the following Message-Button-IDs returned by the dialog box:
 | Value | Meaning
 | IDABORT | Abort button was selected.
 | IDCANCEL | Cancel button was selected. If a message box has a Cancel button, the IDCANCEL value will be returned if either the Escape key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing the Escape key has no effect.
 | IDIGNORE | Ignore button was selected.
 | IDNO | No button was selected.
 | IDOK | OK button was selected.
 | IDRETRY | Retry button was selected.
 | IDYES | Yes button was selected.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the parent window of the message box to be created. If the value of this parameter is zero, the message box will have no parent window.
TEXT | alphanumeric | A string containing the message to be displayed.
TITLE | alphanumeric | A string to be used for the dialog box title. If the value of this parameter is zero, the default title Error is used.
MESSAGE-BOX-FLAGS | windows.cpy | Specifies the contents and behavior of the dialog box. This parameter can be one or more of the following values:
 | Value | Meaning
 | MB-ABORTRETRYIGNORE | The message box contains three push buttons: Abort, Retry, and Ignore.
 | MB-APPLMODAL | The user must respond to the message box before continuing work in the window identified by the WND-H parameter. However, the user can move to the windows or other applications and work in those windows. MB-APPLMODAL is the default if neither MB-SYSTEMMODAL nor MB-TASKMODAL is specified.
 | MB-DEFBUTTON1 | The first button is the default. Note that the first button is always the default unless MB-DEFBUTTON2 or MB-DEFBUTTON3 is specified.
 | MB-DEFBUTTON2 | The second button is the default.
 | MB-DEFBUTTON3 | The third button is the default.
 | MB-ICONASTERISK | Same as MB-ICONINFORMATION.
 | MB-ICONEXCLAMATION | An exclamation-point icon appears in the message box.
 | MB-ICONHAND | Same as MB-ICONSTOP.
 | MB-ICONINFORMATION | An icon consisting of a lowercase letter “l” in a circle appears in the message box.
 | MB-ICONQUESTION | A question-mark icon appears in the message box.
 | MB-ICONSTOP | A stop-sign icon appears in the message box.
 | MB-OK | The message box contains one push button: OK.
 | MB-OKCANCEL | The message box contains two push buttons: OK and Cancel.
 | MB-RETRYCANCEL | The message box contains two push buttons: Retry and Cancel.
 | MB-SYSTEMMODAL | All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). This flag has no effect on the user's ability to interact with windows other than those associated with the parent window specified in the WND-H parameter.
 | MB-TASKMODAL | Same as MB-APPLMODAL, except that all the top-level windows belonging to the current task are disabled if the WND-H parameter is zero. This flag should be used when the calling application or library does not have a window handle available but still needs to prevent input to other windows in the current application without suspending other applications.
 | MB-YESNO | The message box contains two push buttons: Yes and No.
 | MB-YESNOCANCEL | The message box contains three push buttons: Yes, No, and Cancel.


WOWMOVE

WOW Function

The WOWMOVE function moves a form or an intrinsic or ActiveX control. Moving a control within a form is always relative to the origin (0,0), which is the upper-left corner of the form.

Calling Sequence

CALL WOWMOVE USING WIN-RETURN WNDORACTIVEX-H LEFT TOP WIDTH HEIGHT.

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is nonzero if the function is successful. Otherwise, it is zero.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle of an intrinsic or ActiveX control or form that is to be moved.

LEFT

numeric

Indicates the horizontal coordinate for the left edge of object.

TOP

numeric

Indicates the vertical coordinate for the top edge of object.

WIDTH

numeric

Indicates the new width of object.

HEIGHT

numeric

Indicates the new height of object.


WOWMULTICONTROLGETPROP

WOW Function

The WOWMULTICONTROLGETPROP function retrieves the value of one or more properties for multiple intrinsic or ActiveX controls.

Calling Sequence

CALL WOWMULTICONTROLGETPROP USING WIN-RETURN WNDORACTIVEX-H…
PROPERTY-NAME… PROPERTY-VALUE… .

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is always zero.

WNDORACTIVEX-H...

PIC 9(10) BINARY(8)
or PIC X(8)

The handle that identifies an intrinsic or ActiveX control that retrieves property value(s). The WNDORACTIVEX-H parameter can be repeated

PROPERTY-NAME…

alphanumeric

Name of property for which the value is to be retrieved. The PROPERTY-NAME parameter can be repeated.

PROPERTY-VALUE…

alphanumeric
or numeric

Data item in which to store the property value. The PROPERTY-VALUE parameter can be repeated.


WOWMULTICONTROLSETPROP

WOW Function

The WOWMULTICONTROLSETPROP function retrieves the value of one or more properties for multiple intrinsic or ActiveX controls.

Calling Sequence

CALL WOWMULTICONTROLSETPROP USING WIN-RETURN WNDORACTIVEX-H…
PROPERTY-NAME… PROPERTY VALUE… .

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is always zero.

WNDORACTIVEX-H…

PIC 9(10) BINARY(8)
or PIC X(8)

The handle that identifies an intrinsic or ActiveX control for which to set property value(s). The WNDORACTIVEX-H parameter can be repeated.

PROPERTY-NAME…

alphanumeric

Name of property for which to set the value. The PROPERTY-NAME parameter can be repeated.

PROPERTY-VALUE…

alphanumeric
or numeric

New value for the property. The PROPERTY-VALUE parameter can be repeated.


WOWPEEKMESSAGE

WOW Function

The WOWPEEKMESSAGE function can be used to see if any messages are waiting in the message queue.

The WOWGETMESSAGE function is used to retrieve messages from the message queue, but if the queue is empty it will wait for a message before returning. The WOWPEEKMESSAGE function can be used to see if messages are waiting before WOWGETMESSAGE is called. This can be useful in situations such as looking for a cancel button press during report printing.

Calling Sequence

CALL WOWPEEKMESSAGE USING WIN-RETURN.

 | Parameter | Declaration | Description
WIN-RETURN |  | numeric | The return value is nonzero if one or more messages are waiting in the message queue. If no messages are waiting, it is zero.


WOWREFRESH

WOW Function

The WOWREFRESH function forces an immediate repaint or update of an intrinsic or ActiveX control.

Use this method to force a complete repaint of a control.

Generally, painting a control is handled automatically while no events are occurring. However, there may be situations where you want the control updated immediately.

Calling Sequence

CALL WOWREFRESH USING WIN-RETURN WNDORACTIVEX-H.

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is nonzero if the function is successful. Otherwise, it is zero.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle of the intrinsic or ActiveX control to repaint.


WOWREMOVEITEM

WOW Function

The WOWREMOVEITEM function removes an item from a list box or combo box at runtime.

Calling Sequence

CALL WOWREMOVEITEM USING WIN-RETURN WND-H INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle that identifies the list box or combo box.
INDEX | numeric | Represents the position within the control of the item to remove. For the first item in a list box or combo box, INDEX = 0.


WOWRESETWAITCURSOR

WOW Function

The WOWRESETWAITCURSOR function decrements the cursor's internal setwait cursor counter. When the counter is zero, WOWRESETWAITCURSOR removes the WAIT cursor type (an hourglass) and returns the cursor to the default shape (usually a diagonal arrow).

See also WOWCLEARWAITCURSOR and WOWSETWAITCURSOR.

Calling Sequence

CALL WOWRESETWAITCURSOR USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.


WOWSETFOCUS

WOW Function

The WOWSETFOCUS function sets the input focus to the given window (that is, either a form or an intrinsic or ActiveX control). All subsequent keyboard input is directed to this window. The window, if any, which previously had the input focus loses it.

The WOWSETFOCUS function sends a WM-KILLFOCUS message to the window that loses the input focus and a WM-SETFOCUS message to the window that receives the input focus. It also activates either the window that receives the focus or the parent of the window that receives the focus.

If a window is active but does not have the focus (that is, no window has the focus), any key pressed will produce the WM-SYSCHAR, WM-SYSKEYDOWN, or WM-SYSKEYUP message. If the VK-MENU key is also pressed, the LPARAM parameter of the message will have bit 30 set. Otherwise, the messages that are produced do not have this bit set.

This function is equivalent to the Windows API SETFOCUS function.

Calling Sequence

CALL WOWSETFOCUS USING PREV-H WNDORACTIVEX-H.

Parameter

Declaration

Description

PREV-H

PIC 9(10) BINARY(8)
or PIC X(8)

The return values is the handle of the window (form or intrinsic or ActiveX control) that previously had the input focus, if the function is successful. It is zero if there is no such window or if the specified handle is invalid.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle of the window (form or intrinsic or ActiveX control) that is to receive the keyboard input. If the value of this parameter is zero, keystrokes are ignored.


WOWSETINDEXPROP

WOW Function

The WOWSETINDEXPROP function sets the value of one index property for certain intrinsic controls, including status bar, tab, and toolbar.

Note This function is not available for WOW Thin Client.

Calling Sequence

CALL WOWSETINDEXPROP USING WIN-RETURN WND-H PROPERTY-NAME
PROPERTY-VALUE INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.
ACTIVEXCTL-H | PIC X(8) | The handle that identifies the control.
PROPERTY-NAME | alphanumeric | Literal or data item containing the property name.
PROPERTY-VALUE | alphanumeric or numeric | Data item that will receive the property value.
INDEX | numeric | Literal or data item that is the occurrence of the index for the property.


WOWSETNEXTCTRL

WOW Function

The WOWSETNEXTCTRL function moves input focus to the next control in the window.

This function works by determining which control in the window has input focus, then moves input focus to the next control based on the window definition. It will only work if the WOW Extensions form is active and one of the controls on the form has input focus.

CALL WOWSETNEXTCTRL USING WIN-RETURN.

 | Parameter | Declaration | Description
WIN-RETURN |  | numeric | The return value is always zero.


WOWSETNUM

WOW Function

The WOWSETNUM function sets the text of a control or window to a representation of a numeric value, including decimals.

This function makes it easy to use edit fields for entry of numeric data by performing the conversion between numeric data and text. The same type of conversion is also applied by the WOWSETPROP and WOWGETPROP functions if a numeric parameter is supplied for an alphanumeric property.

Calling Sequence

CALL WOWSETNUM USING WIN-RETURN WND-H NUMERIC-VALUE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window for which to set the numeric value of text.
NUMERIC-VALUE | numeric | Numeric value to convert to text for the window.


WOWSETPREVCTRL

WOW Function

The WOWSETPREVCTRL function moves input focus to the previous control in the window.

This function works by determining which control in the window has input focus, then moves input focus to the previous control based on the window definition. It will only work if the WOW Extensions form is active and one of the controls on the form has input focus.

Calling Sequence

CALL WOWSETPREVCTRL USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.


WOWSETPROP

WOW Function

The WOWSETPROP function can be used to set one or more property values for a form, or an intrinsic or ActiveX control at runtime.

The ability to set multiple property values makes WOWSETPROP the preferred method for setting property values.

Note Using WOWSETPROP to set the width or height of a form affects the client area of that form (that is, the area inside a form), but not the overall size of the form. Contrast this behavior with that of MOVEWINDOW, which, when used to move or resize a form, will set the absolute size of that form, including borders and title bar. Providing identical values to WOWSETPROP and MOVEWINDOW for width and height will result in forms of different sizes.

Calling Sequence

CALL WOWSETPROP USING WIN-RETURN WNDORACTIVEX-H
PROPERTY-NAME… PROPERTY-VALUE….

Parameter

Declaration

Description

WIN-RETURN

windows.cpy

The return value is always zero.

WNDORACTIVEX-H

PIC 9(10) BINARY(8)
or PIC X(8)

The handle that identifies the form, or the intrinsic or ActiveX control for which to set property value(s).

PROPERTY-NAME…

alphanumeric

Name of property for which to set the value. The PROPERTY-NAME parameter can be repeated.

PROPERTY-VALUE…

alphanumeric
or numeric

New value for the property. The PROPERTY-VALUE parameter can be repeated.


WOWSETSTRIPTRAILING

WOW Function

The WOWSETSTRIPTRAILING function causes the Wow Extensions runtime either to remove (strip) or not remove trailing spaces when moving COBOL strings to and from intrinsic or ACTIVEX controls.

Calling Sequence

CALL WOWSETSTRIPTRAILING USING STATE.

 | Parameter | Declaration | Description
STATE |  | windows.cpy | Specifies whether the WOW Extensions runtime will remove trailing spaces. If the value of this parameter is WIN-TRUE, trailing spaces will be removed. If the value of this parameter is WIN-FALSE, trailing spaces will not be removed.


WOWSETWAITCURSOR

WOW Function

The WOWSETWAITCURSOR function changes the default cursor shape (usually a diagonal arrow) to the WAIT cursor type (an hourglass). It also increments an internal counter that is used by WOWRESETWAITCURSOR to determine when to restore the cursor to its previous shape.

Calling Sequence

CALL WOWSETWAITCURSOR USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the function is successful.


WOWSTARTMODAL

WOW Function

The WOWSTARTMODAL function makes the specified window modal, disabling all other application windows.

The window specified by WND-H must be a top-level window. The modal behavior of the window can be canceled by removing the window or by using the WOWENDMODAL function.

Modal windows are typically displayed with a dialog border.

Calling Sequence

CALL WOWSTARTMODAL USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | Handle of window to make modal.


WOWVERSION

WOW Function

The WOWVERSION function returns an alphanumeric value containing the version number of the WOW Extensions runtime being used.

The version number is in the format X.Y.Z, where:

· X is the major version number

· Y is the minor version number

· Z is a maintenance version number

Calling Sequence

CALL WOWVERSION USING WIN-RETURN VERSION.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
VERSION | alphanumeric | Version number.


Windows API Functions

See Also

The Windows API functions used in WOW Extensions can be grouped into the following categories:

· Character Functions

· Class Functions

· Device Context/GDI Functions

· Dialog Functions

· Font Functions

· Menu Functions

· Profile Functions

· Scroll Bar Functions

· System Functions

· Window Functions


Character Functions

The Windows API character functions operate on character data.

The following table summarizes the character functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
ANSITOOEM | Translates a string in the ANSI character set to a string in the OEM character set.
ANSITOOEMBUFF | Converts a buffer containing ANSI characters to a buffer containing the corresponding OEM characters.
ISCHARALPHA | Determines whether a character is in the set of language-defined alphabetic characters.
ISCHARALPHANUMERIC | Determines whether a character is in the set of language-defined alphabetic or numeric characters.
ISCHARLOWER | Determines whether a character is in the set of language-defined lowercase characters.
ISCHARUPPER | Determines whether a character is in the set of language-defined uppercase characters.
OEMTOANSI | Translates a string from the OEM character set into the ANSI character set.
OEMTOANSIBUFF | Converts a buffer containing OEM characters to a buffer containing the corresponding ANSI characters.
VKKEYSCAN | Translates a Windows character to the corresponding virtual-key code and shift state for the current keyboard.


ANSITOOEM

Character Windows API Function

The ANSITOOEM function translates a string in the ANSI character set to a string in the OEM character set. For most computers, the OEM character set is code page 437. Strings longer than 64K may be translated. The WOW Extensions runtime’s Euro character processing is used.

Calling Sequence

CALL ANSITOOEM USING WINDOWSSTR OEMSTR.

Parameter | Declaration | Description
WINDOWSSTR | alphanumeric | A string of characters from the ANSI character set.
OEMSTR | alphanumeric | The location where the translated string is to be copied. To translate the string in place, the WINDOWSSTR parameter can be the same as the OEMSTR parameter.


ANSITOOEMBUFF

Character Windows API Function

The ANSITOOEMBUFF function translates a string containing ANSI characters to a buffer containing the corresponding OEM characters.

Calling Sequence

CALL ANSITOOEMBUFF USING WINDOWSSTR OEMSTR STR-SIZE.

Parameter | Declaration | Description
WINDOWSSTR | alphanumeric | A buffer containing one or more string(s) of characters from the ANSI character set.
OEMSTR | alphanumeric | The location where the translated string is to be copied. To translate the string in place, the WINDOWSSTR parameter can be the same as the OEMSTR parameter.
STR-SIZE | numeric | Specifies the length, in bytes, of the string pointed to by WINDOWSSTR. If STR-SIZE is zero, the size will be calculated automatically.


ISCHARALPHA

Character Windows API Function

The ISCHARALPHA function determines whether a character is in the set of language-defined alphabetic characters. The language driver for the current language (the language the user selected at setup or by using Control Panel) determines whether the character is in the set. If no language has been set, Windows uses an internal function.

Calling Sequence

CALL ISCHARALPHA USING WIN-RETURN TEST-CH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the character is in the set of alphabetic characters. Otherwise, it is zero.
TEST-CH | alphanumeric | Specifies the character to be tested.


ISCHARALPHANUMERIC

Character Windows API Function

The ISCHARALPHANUMERIC function determines whether a character is in the set of language-defined alphabetic or numeric characters. The language driver for the current language (the language the user selected at setup or by using Control Panel) determines whether the character is in the set. If no language driver is selected, Windows uses an internal function.

Calling Sequence

CALL ISCHARALPHANUMERIC USING WIN-RETURN TEST-CH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the character is in either the set of alphabetic characters or the set of numeric characters. Otherwise, it is zero.
TEST-CH | alphanumeric | Specifies the character to be tested.


ISCHARLOWER

Character Windows API Function

The ISCHARLOWER function determines whether a character is in the set of language-defined lowercase characters. The language driver for the current language (the language selected at setup or by using Control Panel) determines whether the character is in the set. If no language driver is selected, Windows uses an internal function.

Calling Sequence

CALL ISCHARLOWER USING WIN-RETURN TEST-CH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the character is lowercase. Otherwise, it is zero.
TEST-CH | alphanumeric | Specifies the character to be tested.


ISCHARUPPER

Character Windows API Function

The ISCHARUPPER function determines whether a character is in the set of language-defined uppercase characters. The language driver for the current language (the language the user selected at setup or by using Control Panel) determines whether the character is in the set. If no language driver is selected, Windows uses an internal function.

Calling Sequence

CALL ISCHARUPPER USING WIN-RETURN TEST-CH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the character is uppercase. Otherwise, it is zero.
TEST-CH | alphanumeric | Specifies the character to be tested.


OEMTOANSI

Character Windows API Function

The OEMTOANSI function translates a string from the OEM character set into the ANSI character set.

Calling Sequence

CALL OEMTOANSI USING OEMSTR WINDOWSSTR.

Parameter | Declaration | Description
OEMSTR | alphanumeric | A string of characters from the OEM character set.
WINDOWSSTR | alphanumeric | The location where the translated string is to be copied. To translate the string in place, the WINDOWSSTR parameter can be the same as the OEMSTR parameter.


OEMTOANSIBUFF

Character Windows API Function

The OEMTOANSIBUFF function converts a buffer containing OEM characters to a buffer containing the corresponding ANSI characters.

Calling Sequence

CALL OEMTOANSIBUFF USING OEMSTR WINDOWSSTR STR-SIZE.

Parameter | Declaration | Description
OEMSTR | alphanumeric | A buffer containing one or more characters from the OEM character set.
WINDOWSSTR | alphanumeric | The location where the translated string is to be copied. To translate the string in place, the WINDOWSSTR parameter can be the same as the OEMSTR parameter.
STR-SIZE | numeric | Specifies the length, in bytes, of the buffer pointed to by OEMSTR. If STR-SIZE is zero, the size will be calculated automatically.


VKKEYSCAN

Character Windows API Function

The VKKEYSCAN function translates a Windows character to the corresponding virtual-key code and shift state for the current keyboard.

Translations for the numeric keypad (VK-NUMPAD0 through VK-DIVIDE) are ignored. This function is intended to force a translation for the main keyboard only.

Applications that send characters by using the WM-KEYUP and WM-KEYDOWN messages use this function.

Calling Sequence

CALL VKKEYSCAN USING WIN-RETURN CHAR.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the virtual-key code and shift state, if the function is successful. The low-order byte contains the virtual-key code; the high-order byte contains the shift state, which can be one of the following:
 | Value | Meaning
 | 1 | Character is shifted.
 | 2 | Character is a control character.
 | 3 - 5 | Shift-key combination that is not used for characters.
 | 6 | Character is generated by the CTRL+ALT key combination.
 | 7 | Character is generated by the SHIFT+CTRL+ALT key combination.
 |  | If no key is found that translates to the passed Windows code, the return value is -1.
CHAR | numeric or alphanumeric | Specifies the character to be translated to a virtual-key code.


Class Functions

The Windows API class functions apply to window classes. A window class contains information that determines how a window looks and behaves. There are three types of window classes:

· System Class. A window class registered by the system.

· Global Class. A window class registered by an executable or dynamic-link library (DLL) that is available to all other modules in the process.

· Application Local Class. Any window class that an executable or DLL registers for its exclusive use.

These types differ in scope and in when and how they are registered and destroyed.

The following table summarizes the class functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
GETCLASSINFO | Retrieves information about a specific window class.
GETCLASSLONG | Retrieves a 32-bit (long) value, at the specified offset from the extra class memory for the window class associated with the given window.
GETCLASSNAME | Retrieves the class name of a window.
GETCLASSWORD | Retrieves a two-byte word value at the specified offset from the extra class memory for the window class associated with the given window.
REGISTERCLASS | Registers a window class for subsequent use in calls to the CREATEWINDOW function.
SETCLASSLONG | Sets a long value at the specified offset in the extra class memory for the window class associated with the given window.
SETCLASSWORD | Sets a word value at the specified offset in the extra class memory for the window class associated with the given window.
UNREGISTERCLASS | Removes a window class, freeing the storage required for the class.


GETCLASSINFO

Class Windows API Function

The GETCLASSINFO function retrieves information about a window class. This function is used for creating subclasses of a given class. The GETCLASSINFO function does not set the CLASSNAME and MENUNAME members of the WNDCLASS structure. The menu name is not stored internally and cannot be returned. The class name is already known, since it is passed to this function. GETCLASSINFO returns all other members with the values used when the class was registered.

Calling Sequence

CALL GETCLASSINFO USING WIN-RETURN INST-H CLASSNAME WNDCLASS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero, indicating the function did not find a matching class.
INST-H | PIC 9(10) BINARY(8) | Identifies the instance of the application that created the class. To retrieve information about classes defined by Windows (such as buttons or list boxes), set this parameter to zero.
CLASSNAME | alphanumeric | Specifies the class name. The class name is either an application-specified name as defined by the REGISTERCLASS function or the name of a pre-registered window class.
WNDCLASS | windows.cpy | A structure that receives the information about the class.


GETCLASSLONG

Class Windows API Function

The GETCLASSLONG function retrieves a 32-bit (long) value at the specified offset into the extra class memory for the window class to which the given window belongs. Extra class memory is reserved by specifying a nonzero value in the CBCLSEXTRA member of the WNDCLASS structure used with the REGISTERCLASS .

To access any extra four-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first four-byte value in the extra space, 4 for the next four-byte value, and so on.

Since this is a four-byte return value, special handling is required, as illustrated in the following example:

CALL GETCLASSLONG USING WIN-RETURN WND-H VALUE.

where VALUE is one of a set of predefined values. These values are specified in the Windows API documentation and the Windows include files. They are not included in the current version of windows.cpy.

Calling Sequence

CALL GETCLASSLONG USING WIN-RETURN WND-H OFFSET.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the specified 4four-byte value in the extra class memory if the function is successful. Otherwise, it is zero, indicating the WND-H or OFFSET parameter is invalid.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of class memory minus four (for example, if 12 or more bytes of extra class memory was specified, a value of 8 would be an index to the third -4 byte value) or one of the following values:
 | Value | Meaning
 | GCL-MENUNAME | Retrieves a 32-bit pointer to the menu-name string.
 | GCL-WNDPROC | Retrieves a 32-bit pointer to the window procedure.


GETCLASSNAME

Class Windows API Function

The GETCLASSNAME function retrieves the class name of a window.

Calling Sequence

CALL GETCLASSNAME USING WIN-RETURN WND-H CLASSNAME CLASSNAME-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the returned class name. The return value is zero if the specified window handle is invalid.
WND-H | PIC 9(10) BINARY(8) | The handle of the window for which class name is being retrieved.
CLASSNAME | alphanumeric | Receives the class name.
CLASSNAME-SIZE | numeric | Specifies the length of the CLASSNAME parameter. The class name is truncated if it is longer than the buffer. If this value is zero, the size of the buffer will be automatically calculated.


GETCLASSWORD

Class Windows API Function

The GETCLASSWORD function retrieves a two-byte value at the specified offset into the extra class memory for the window class to which the given window belongs. Extra class memory is reserved by specifying a nonzero value in the CBCLSEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

To access any extra two-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first two-byte value in the extra space, 2 for the next two-byte value, and so on.

Calling Sequence

CALL GETCLASSWORD USING WIN-RETURN WND-H OFFSET.

 | Parameter | Declaration | Description
WIN-RETURN |  | numeric | The return value is the two-byte value in the window’s reserved memory, if the function is successful. Otherwise, it is zero, indicating the WND-H or OFFSET parameter is invalid.
 | WND-H | PIC 9(10) BINARY(8) | The handle of the window for which the value is to be retrieved.
 | OFFSET | numeric | Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of class memory minus two (for example, if 10 or more bytes of extra class memory was specified, a value of 8 would be an index to the fifth two-byte value) or one of the following values:
 |  | Value | Meaning
 |  | GCW-CBCLSEXTRA | Retrieves the number of bytes of additional class information.
 |  | GCW-CBWNDEXTRA | Retrieves the number of bytes of additional window information.
 |  | GCW-HBRBACKGROUND | Retrieves the handle of the background brush.
 |  | GCW-HCURSOR | Retrieves the handle of the cursor.
 |  | GCW-HICON | Retrieves the handle of the icon.
 |  | GCW-HMODULE | Retrieves the handle of the module.
 |  | GCW-STYLE | Retrieves the window-class style bits.


REGISTERCLASS

Class Windows API Function

The REGISTERCLASS function registers a window class for subsequent use in calls to the CREATEWINDOW or CREATEWINDOWEX functions.

An application cannot register a global class if either a global class or a task-specific class already exists with the given name.

An application can register a task-specific class with the same name as a global class. The task-specific class overrides the global class for the current task only. A task cannot register two local classes with the same name. However, two different tasks can register task-specific classes using the same name.

Calling Sequence

CALL REGISTERCLASS USING WIN-RETURN WND-CLASS.

 | Parameter | Declaration | Description
WIN-RETURN |  | numeric | The return value is an atom that uniquely identifies the class being registered.
WND-CLASS |  | windows.cpy | A WNDCLASS structure, declared under “WNDCLASS GLOBAL” in windows.cpy. The structure must be filled with the appropriate class attributes before being passed to the function.


SETCLASSLONG

Class Windows API Function

The SETCLASSLONG function sets a long value at the specified offset into the extra class memory for the window class to which the specified window belongs. Extra class memory is reserved by specifying a nonzero value in the CBCLSEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

To access any extra four-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the INDEX parameter, starting at 0 for the first four-byte value in the extra space, 4 for the next four-byte value, and so on.

Calling Sequence

CALL SETCLASSLONG USING WIN-RETURN WND-H OFFSET VAL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the previous value of the specified long integer, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the long value to change. Valid values are in the range zero through the number of bytes of class memory, minus four. (For example, if 12 or more bytes of extra class memory were specified, a value of 8 would be an index to the third long integer.)
VAL | numeric | Specifies the replacement value.


SETCLASSWORD

Class Windows API Function

The SETCLASSWORD function sets a word value at the specified offset into the extra class memory for the window class to which the given window belongs. Extra class memory is reserved by specifying a nonzero value in the CBCLSEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

The SETCLASSWORD function should be used with care. For example, it is possible to change the background color for a class by using SETCLASSWORD, but this change does not cause all windows belonging to the class to be repainted immediately. Applications should not attempt to set the class word values of any class attribute except those listed for the OFFSET parameter.

To access any extra two-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first two-byte value in the extra space, 2 for the next two-byte value, and so on.

Calling Sequence

CALL SETCLASSWORD USING WIN-RETURN WND-H OFFSET VAL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the previous value of the specified word, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the word value to change. Valid values are in the range zero through the number of bytes of class memory, minus two (for example, if 10 or more bytes of extra class memory were specified, a value of 8 would be an index to the fifth integer), or one of the following values:
 | Value | Meaning
 | GCW-HBRBACKGROUND | Sets a new handle of a background brush.
 | GCW-HCURSOR | Sets a new handle of a cursor.
 | GCW-HICON | Sets a new handle of an icon.
 | GCW-STYLE | Sets a new style bit for the window class.
VAL | numeric | Specifies the replacement value.


UNREGISTERCLASS

Class Windows API Function

The UNREGISTERCLASS function removes a window class, freeing the storage required for the class.

Before calling this function, an application should destroy all windows that were created with the specified class.

Calling Sequence

CALL UNREGISTERCLASS USING WIN-RETURN CLASSNAME INST-H.

 | Parameter | Declaration | Description
WIN-RETURN |  | numeric | The return value is nonzero if the function is successful. It is zero if the class could not be found or if a window exists that was created with the class.
CLASSNAME |  | alphanumeric | A null-terminated string containing the class name. This class name must have been registered by a previous call to the REGISTERCLASS function with a valid INST-H member of the WNDCLASS structure. Predefined classes, such as dialog box controls, cannot be unregistered.
INST-H |  | PIC 9(10) BINARY(8) | Identifies the instance of the module that created the class.


Device Context/GDI Functions

A device context (DC) is a link between a Windows application, a device driver, and an output device. The Windows API device context/GDI functions create, delete, and restore device contexts.

The following table summarizes the device context functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
CREATEIC | Creates an information context for the specified device.
DELETEDC | Deletes a device context created with the CREATEIC function.
DELETEOBJECT | Deletes an object from memory by freeing all system storage associated with the object.
DESTROYICON | Destroys an icon and frees any memory the icon occupied.
GETCURSORPOS | Retrieves the cursor's position, in screen coordinates.
GETDEVICECAPS | Retrieves device-specific information about a given display device.
GETSTOCKOBJECT | Retrieves a handle of one of the predefined stock pens, brushes, fonts, or color palettes.
SETCURSORPOS | Moves the cursor to the specified screen coordinates.


CREATEIC

Device Context/GDI Windows API Function

The CREATEIC function creates an information context for the specified device. The information context provides a fast way to get information about the device without creating a device context.

MS-DOS device names follow MS-DOS conventions; an ending colon is recommended, but optional. Windows strips the terminating colon so that a device name ending with a colon is mapped to the same port as would be the same name without a colon.

The driver and port names must not contain leading or trailing spaces.

GDI output functions cannot be used with information contexts.

When it has finished using an information context created by CREATEIC, an application should remove the information context by using the DELETEDC function.

Calling Sequence

CALL CREATEIC USING DC-H DEVICE-DRIVER DEVICE-NAME OUTPUT-DEVICE.

Parameter | Declaration | Description
DC-H | PIC 9(10) BINARY(8) | The return value is the handle of an information context for the given device if the function is successful. Otherwise, it is zero.
DEVICE-DRIVER | alphanumeric | Points to a null-terminated string that specifies the MS-DOS filename (without extension) of the device driver (for example, EPSON).
DEVICE-NAME | alphanumeric | Points to a null-terminated spring that specifies the name of the specific device to be supported (for example, EPSON FX-80). This parameter is used if the module supports more than one device.
OUTPUT-DEVICE | alphanumeric | Points to a null-terminated string that specifies the MS-DOS filename or device name for the physical output medium (file or port).


DELETEDC

Device Context/GDI Windows API Function

The DELETEDC function is used to delete a device context. This function should be used to delete information contexts created with the CREATEIC function.

Calling Sequence

CALL DELETEDC USING WIN-RETURN DC-H.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
DC-H | PIC 9(10) BINARY(8) | The handle of the device context to delete.


DELETEOBJECT

Device Context/GDI Windows API Function

The DELETEOBJECT function deletes an object from memory by freeing all system storage associated with the object. (Objects include pens, brushes, fonts, bitmaps, regions, and palettes.) After the object is deleted, the handle given in the GDIOBJ-H parameter is no longer valid.

An application should not delete an object that is currently selected into a device context.

When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently.

Calling Sequence

CALL DELETEOBJECT USING WIN-RETURN GDIOBJ-H.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
GDIOBJ-H | PIC 9(10) BINARY(8) | The handle of the object to be deleted. It identifies a pen, brush, font, bitmap, region, or palette.


DESTROYICON

Device Context/GDI Windows API Function

The DESTROYICON function destroys an icon and frees any memory the icon occupied.

Calling Sequence

CALL DESTROYICON USING WIN-RETURN ICON-H.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
ICON-H | PIC 9(10) BINARY(8) | The handle of the icon to destroy. The icon must not be in use.


GETCURSORPOS

Device Context/GDI Windows API Function

The GETCURSORPOS function retrieves the cursor's position, in screen coordinates.

Calling Sequence

Call GetCursorPos Using Win-Return Point-X Point-Y.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
POINT X | PIC 9(5) BINARY(4) | Specifies the X coordinate of the point.
POINT Y | PIC 9(5) BINARY(4) | Specifies the Y coordinate of the point.


GETDEVICECAPS

Device Context/GDI Windows API Function

The GETDEVICECAPS function retrieves device-specific information about a given display device.

Calling Sequence

CALL GETDEVICECAPS USING WIN-RETURN DC-H CAPABILITY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the value of the requested capability if the function is successful. Otherwise, it is zero.
DC-H | PIC 9(10) BINARY(8) | The handle of the device context.
CAPABILITY | windows.cpy | Specifies the type of information to be returned. It can be one of the following values:
 | Index | Description
 | DRIVERVERSION | Version number of the device driver.
 | TECHNOLOGY | Device technology. It can be one of the following values:
 |  | Value |  | Meaning
 |  | DT-PLOTTER |  | Vector plotter
 |  | DT-RASDISPLALY |  | Raster display
 |  | DT-RASPRINTER |  | Raster printer
 |  | DT-RASCAMERA |  | Raster camera
 |  | DT-CHARSTREAM |  | Character stream
 |  | DT-METAFILE |  | Metafile
 |  | DT-DISPFILE |  | Display file
 | HORZSIZE | Width of the physical display, in millimeters.
 | VERTSIZE | Height of the physical display, in millimeters.
 | HORZRES | Width of the display, in pixels.
 | VERTRES | Height of the display, in raster lines.
 | LOGPIXELSX | Number of pixels per logical inch along the display width.
 | LOGPIXELSY | Number of pixels per logical inch along the display height.
 | BITSPIXEL | Number of adjacent color bits for each pixel.
 | PLANES | Number of color planes.
 | NUMBRUSHES | Number of device-specific brushes.
 | NUMPENS | Number of device-specific pens.
 | NUMMARKERS | Number of device-specific markers.
 | NUMFONTS | Number of device-specific fonts
 | NUMCOLORS | Number of entries in the device’s color table.
 | ASPECTX | Relative width of a device pixel used for line drawing.
 | ASPECTXY | Diagonal width of a device pixel used for line drawing.
 | PDEVICESIZE | Size of the PDEVICE internal structure, in bytes.
 | CLIPCAPS | Clipping capabilities the device supports. It can be one of the following values:
 |  | Value | Meaning
 |  | CP-NONE | Output is not clipped.
 |  | CP-RECTANGLE | Output is clipped to rectangles.
 |  | CP-REGION | Output is clipped to regions.
 | SIZEPALETTE | Number of entries in the system palette. This index is valid only if the driver sets the RC-PALETTE bit in the RASTERCAPS index; it is available only if the driver is written for Windows 3.0 or later.
 | NUMRESERVED | Number of reserved entries in the system palette. This index is valid only if the device sets the RC-PALETTE bit in the RASTERCAPS index; it is available only if the driver is written for Windows 3.0 or later.
 | COLORRES | Color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC-PALETTE bit in the RASTERCAPS index; it is available only if the driver is written for Windows 3.0 or later.
 | RASTERCAPS | Raster capabilities the device supports. It can be one or more of the following values:
 |  | Value | Meaning
 |  | RC-BANDING | Supports banding.
 |  | RC-BIGFONT | Supports fonts larger than 64K.
 |  | RC-BITBLT | Transfers bitmaps.
 |  | RC-BITMAP64 | Supports bitmaps larger than 64K.
 |  | RC-DEVBITS | Supports device bitmaps.
 |  | RC-DI-BITMAPS | Supports the SETDLBITS and GETDLBITS functions.
 |  | RC-DIBTODEV | Supports the SETDLBITSTODEVICE function.
 |  | RC-FLOODFILL | Performs flood fills.
 |  | RC-GD120-OUTPUT | Supports Windows version 2.0 features.
 |  | RC-GD120-STATE | Includes a state block in the device context.
 |  | RC-NONE | Supports no raster operations.
 |  | RC-OP-DX-OUTPUT | Supports dev opaque and DX array.
 |  | RC-PALETTE | Specifies a palette-based device.
 |  | RC-SAVEBITMAP | Saves bitmaps locally.
 |  | RC-SCALING | Supports scaling.
 |  | RC-STRETCHBLT | Supports the STRETCHBIT function.
 |  | RC-STRETCHDIB | Supports the STRETCHDLBITS function.
 | CURVECAPS | Curve capabilities the device supports. It can be one or more of the following values:
 |  | Value | Meaning
 |  | CC-NONE | Supports curves.
 |  | CC-CIRCLES | Supports circles.
 |  | CC-PIE | Supports pie wedges.
 |  | CC-CHORD | Supports chords.
 |  | CC-ELLIPSES | Supports ellipses.
 |  | CC-WIDE | Supports wide borders.
 |  | CC-STYLED | Supports styled borders.
 |  | CC-WIDESTYLED | Supports wide, styled borders.
 |  | CC-INTERIORS | Supports interiors.
 |  | CC-ROUNDRECT | Supports rectangles with rounded corners.
 | LINECAPS | Line capabilities the device supports. It can be one or more of the following values:
 |  | Value | Meaning
 |  | LC-NONE | Supports no lines.
 |  | LC-POLYLINE | Supports polylines.
 |  | LC-MARKER | Supports markers.
 |  | LC-POLYMARKER | Supports polymarkers.
 |  | LC-WIDE | Supports wide lines.
 |  | LC-STYLED | Supports styled lines.
 |  | LC-WIDESTYLED | Supports wide, styled lines.
 |  | LC-INTERIORS | Supports interiors.
 | POLYGONALCAPS | Polygonal capabilities the device supports. It can be one or more of the following values:
 |  | Value | Meaning
 |  | PC-NONE | Supports no polygons.
 |  | PC-POLYGON | Supports alternate fill polygons.
 |  | PC-RECTANGLE | Supports rectangles.
 |  | PC-WINDPOLYGON | Supports winding number fill polygons.
 |  | PC-SCANLINE | Supports scan lines.
 |  | PC-WIDE | Supports wide borders.
 |  | PC-STYLED | Supports styled borders.
 |  | PC-WIDESTYLED | Supports wide, styled borders.
 |  | PC-INTERIORS | Supports interiors.
 | TEXTCAPS | Text capabilities the device supports. It can be one or more of the following devices:
 |  | Value | Meaning
 |  | TC-OP-CHARACTER | Supports character output precision, which indicates the device can place device fonts at any pixel location. This is required for any device with device fonts.
 |  | TC-OP-STROKE | Supports stroke output precision, which indicates the device can omit any stroke of a device font.
 |  | TC-CP-STROKE | Supports stroke clip precision, which indicates the device can clip device fonts to a pixel boundary.
 |  | TC-CR-90 | Supports 90-degree character rotation, which indicates the device can rotate characters only 90 degrees at a time.
 |  | TC-CR-ANY | Supports character rotation at any degree, which indicates the device can rotate device fonts through any angle.
 |  | TC-SF-X-YINDEP | Supports scaling independent of X and Y directions, which indicates the device can scale device fonts separately in X and Y directions.
 |  | TC-SA-DOUBLE | Supports doubled characters for scaling, which indicates the device can double the size of device fonts.
 |  | TC-SA-INTEGER | Supports integer multiples for scaling, which indicates the device can scale the size of device fonts in any integer multiple.
 |  | TC-SA-CONTIN | Supports any multiples for exact scaling, which indicates the device can scale device fonts by any amount but still preserve the X and Y ratios.
 |  | TC-EA-DOUBLE | Supports double-weight-characters, which indicate the device can make device fonts bold. If this bit is not set for printer drivers, graphics device interface (GDI) attempts to create bold device fonts by printing them twice.
 |  | TC-IA-ABLE | Supports italics, which indicates the device can make device fonts italic. If this bit is not set, GDI assumes italics are not available.
 |  | TC-UA-ABLE | Supports underlining, which indicates the device can underline device fonts. If this bit is not set, GDI creates underlines for device fonts.
 |  | TC-SO-ABLE | Supports strikeouts, which indicates the device can strike out device fonts. If this bit is not set, GDI creates strikeouts for device fonts.
 |  | TC-RA-ABLE | Supports raster fonts, which indicates that GDI should enumerate any raster or TrueType fonts available for this device when enumerating fonts. If this bit is not set, GDI-supplied raster or TrueType fonts are not enumerated when these functions are called.
 |  | TC-VA-ABLE | Supports vector fonts, which indicates that GDI should enumerate any vector fonts available for this device when enumerating fonts. This is significant for vector devices only (that is, for plotters). Display drivers (which must be able to use raster fonts) and raster printer drivers always enumerate vector fonts, because GDI rasterizes vector fonts before sending them to the driver.
 |  | TC-RESERVED | Reserved; must be zero.


GETSTOCKOBJECT

Device Context/GDI Windows API Function

The GETSTOCKOBJECT function retrieves a handle of one of the predefined stock pens, brushes, or fonts. The DKGRAY-BRUSH, GRAY-BRUSH, and LTGRAY-BRUSH objects should be used only in windows with the CS-HREDRAW and CS-VREDRAW class styles. Using a gray stock brush in any other style of window can lead to misalignment of brush patterns after a window is moved or sized. The origins of stock brushes cannot be adjusted.

Calling Sequence

CALL GETSTOCKOBJECT USING OBJ-H OBJECT-TYPE.

Parameter | Declaration | Description
OBJ-H | PIC 9(10) BINARY(8) | The handle of the stock object.
OBJECT-TYPE | windows.cpy | Specifies the type of stock object for which to retrieve a handle. This parameter can be one of the following values:
 | Value | Meaning
 | BLACK-BRUSH | Black brush.
 | DKGRAY-BRUSH | Dark-gray brush.
 | GRAY-BRUSH | Gray brush.
 | HOLLOW-BRUSH | Hollow brush.
 | LTGRAY-BRUSH | Light-gray brush.
 | NULL-BRUSH | Null brush.
 | WHITE-BRUSH | White brush.
 | BLACK-PEN | Black pen.
 | NULL-PEN | Null pen.
 | WHITE-PEN | White pen.
 | ANSI-FIXED-FONT | Windows fixed-pitch system font.
 | ANSI-VAR-FONT | Windows variable-pitch system font.
 | DEVICE-DEFAULT-FONT | Device-dependent font.
 | OEM-FIXED-FONT | System font. By default, Windows uses the system font to draw menus, dialog box controls, and other text. In Windows versions 3.0 and later, the system font is a variable-pitch system font.
 | SYSTEM-FIXED-FONT | Fixed-pitch system font used in Windows versions earlier than 3.0. This object is available for compatibility with earlier versions of Windows.
 | DEFAULT-PALETTE | Default color palette. This palette consists of the static colors in the system palette.


SETCURSORPOS

Device Context/GDI Windows API Function

The SETCURSORPOS function moves the cursor to the specified screen coordinates.

Calling Sequence

Call SetCursorPos Using Win-Return Point-X Point-Y.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
POINT X | PIC 9(5) BINARY(4) | Specifies the X coordinate of the cursor.
POINT Y | PIC 9(5) BINARY(4) | Specifies the Y coordinate of the cursor.


Dialog Functions

The Windows API dialog functions create, alter, test, and destroy dialog boxes and controls within dialog boxes. Since WOW Extensions forms are similar in nature to Windows dialog boxes, all of the following dialog functions can be applied to forms.

The following table summarizes the dialog functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
CHECKDLGBUTTON | Places (selects) or removes (clears) a check mark from a button or check box control. Or, it changes the state of a three-state button or check box.
CHECKRADIOBUTTON | Selects a specified option button in a group and clears all other option buttons in the group.
DLGDIRLIST | Fills a list box with names of files matching a path.
DLGDIRLISTCOMBOBOX | Fills the list box of a combo box with files matching a specified path and filename.
DLGDIRSELECT or DLGDIRSELECTEX | Retrieves the current selection from a list box.
DLGDIRSELECTCOMBOBOX or DLGDIRSELECTCOMBOBOXEX | Retrieves the current selection from the list box of a combo box.
GETDIALOGBASEUNITS | Returns the form base units used by Windows when creating forms.
GETDLGCTRLID | Returns the ID value of a child window.
GETDLGITEM | Retrieves the handle of a control in the given form.
GETDLGITEMINT | Translates the text of a control associated with the given form into an integer.
GETDLGITEMTEXT | Retrieves the title or text associated with a control in a form.
GETNEXTDLGGROUPITEM | Searches for the previous (or next) control within a group of controls in a form and returns the window handle of the next item in a group.
GETNEXTDLGTABITEM | Retrieves the handle of the first control that has the WS-TABSTOP style that precedes (or follows) the specified control.
ISDLGBUTTONCHECKED | Tests whether a button is selected and whether a three-state button is grayed (dimmed), checked, or neither.
SETDLGITEMINT | Sets the text of a given control in a form to the alphanumeric representation that represents a specified integer value.
SETDLGITEMTEXT | Sets the title or text of a control in a form.


CHECKDLGBUTTON

Dialog Windows API Function

The CHECKDLGBUTTON function selects (places a check mark next to) or clears (removes a check mark from) a button control, or it changes the state of a three-state button.

The CHECKDLGBUTTON function sends a BM-SETCHECK message to the specified button control in the given window.

Calling Sequence

CALL CHECKDLGBUTTON USING WND-H BUTTON-ID CHECK-STATE.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the button.
BUTTON-ID | numeric | Specifies the identifier of the button to be modified.
CHECK-STATE | numeric | Specifies the check state of the button. If the value of this parameter is nonzero, CHECKDLGBUTTON selects the button; if the value of this parameter is zero, the function clears the button. For a three-state check box, if CHECK-STATE is 2, the button is grayed; if CHECK-STATE is 1, it is selected; if CHECK-STATE is zero, it is cleared.


CHECKRADIOBUTTON

Dialog Windows API Function

The CHECKRADIOBUTTON function selects (adds a check mark to) a given radio button in a group and clears (removes a check mark from) all other radio buttons in the group.

The CHECKRADIOBUTTON function sends a BM-SETCHECK message to the specified radio button control in the given window.

Calling Sequence

CALL CHECKRADIOBUTTON USING WND-H FIRST-ID LAST-ID CHECK-ID.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the radio button.
FIRST-ID | numeric | Specifies the identifier of the first radio button in the group.
LAST-ID | numeric | Specifies the identifier of the last radio button in the group.
CHECK-ID | numeric | Specifies the identifier of the radio button to select.


DLGDIRLIST

Dialog Windows API Function

The DLGDIRLIST function fills a list box with a file or directory listing. It fills the list box with the names of all files matching the specified path or filename.

If the PATH-NAME parameter is blank or contains only a directory name but does not include any filename, the value will be changed to *.*.

The DLGDIRLIST function shows directories enclosed in brackets ([ ]) and shows drives in the form [-x-], where x is the drive letter.

The PATH-NAME parameter has the following form:

[drive:][[\]directory[\directory]...\][filename]

In this example, drive is a drive letter, directory is a valid MS-DOS directory name, and filename is a valid MS-DOS filename that must contain at least one wildcard. The wildcards are a question mark (?), meaning match any character, and an asterisk (*), meaning match any number of characters.

If the PATH-NAME parameter includes a drive or directory name, or both, the current drive and directory are changed to the specified drive and directory before the list box is filled. The static control identified by the STATIC-PATH-ID parameter is also updated with the new drive or directory name, or both.

After the list box is filled, PATH-NAME is updated by removing the drive or directory portion, or both, of the path and filename.

DLGDIRLIST sends LB-RESETCONTENT and LB-DIR messages to the list box.

Calling Sequence

CALL DLGDIRLIST USING WIN-RETURN WND-H PATH-NAME
LISTBOX-ID STATIC-PATH-ID DLL-WS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the list box.
PATH-NAME | PIC X (260) | Contains the path or filename. DLGDIRLIST modifies this value, which should be 260 bytes long or else the path or filename may be truncated.
LISTBOX-ID | numeric | Specifies the identifier of a list box. If the value of this parameter is zero, DLGDIRLIST assumes that no list box exists and does not attempt to fill one.
STATIC-PATH-ID | numeric | Specifies the identifier of the static control used for displaying the current drive and directory. If the value of this parameter is zero, DLGDIRLIST assumes that no such control is present.
DLL-WS | windows.cpy | Specifies the attributes of the filenames to be displayed. This parameter can be one or more of the following values:
 | Value | Meaning
 | DDL-READWRITE | Read-write data files with no additional attributes.
 | DDL-READONLY | Read-only files.
 | DDL-HIDDEN | Hidden files.
 | DDL-SYSTEM | System files.
 | DDL-DIRECTORY | Directories.
 | DDL-ARCHIVE | Archives.
 | DDL-POSTMSGS | LB-DIR flag. If the LB-DIR flag is set, Windows places the messages generated by DLGDIRLIST in the application’s queue; otherwise, they are sent directly to the dialog box procedure.
 | DDL-DRIVES | Drives. If the DDL-DRIVES flag is set, the DDL-EXCLUSIVE flag is set automatically. Therefore, to create a directory listing that includes drives and files, the developer must call DLGDIRLIST twice: once with the DDL-DRIVES flag set and once with the flags for the rest of the list.
 | DDL-EXCLUSIVE | Exclusive bit. If the exclusive bit is set, only files of the specified type are listed; otherwise, files of the specified type are listed in addition to normal files.


DLGDIRLISTCOMBOBOX

Dialog Windows API Function

The DLGDIRLISTCOMBOBOX function fills the list box of a combo box with a file or directory listing. It fills the list box with the names of all files matching the specified path and filename.

The DLGDIRLISTCOMBOBOX function shows directories enclosed in brackets ([ ]) and shows drives in the form [-x-], where x is the drive letter.

The PATH-NAME parameter has the following form:

[drive:][[\]directory[\directory]...\][filename]

In this example, drive is a drive letter, directory is a valid MS-DOS directory name, and filename is a valid MS-DOS filename that must contain at least one wildcard. The wildcards are a question mark (?), meaning match any character, and an asterisk (*), meaning match any number of characters.

If the PATH-NAME parameter includes a drive or directory name, or both, the current drive and directory are changed to the specified drive and directory before the list box is filled. The static control identified by the STATIC-PATH-ID parameter is also updated with the new drive or directory name, or both.

After the list box of the combo box is filled, PATH-NAME is updated by removing the drive or directory portion, or both, of the path and filename.

DLGDIRLISTCOMBOBOX sends CB-RESETCONTENT and CB-DIR messages to the combo box.

Calling Sequence

CALL DLGDIRLISTCOMBOBOX USING WIN-RETURN WND-H PATH-NAME
COMBOBOX-ID STATIC-PATH-ID DLL-WS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the combo box.
PATH-NAME | PIC X(260) | Contains the path and filename. This field should be 260 bytes long or else the path or filename may be truncated.
COMBOBOX-ID | numeric | Specifies the identifier of a combo box in a window. If the value of this parameter is zero, DLGDIRLISTCOMBOBOX assumes that no combo box exists and does not attempt to fill one.
STATIC-PATH-ID | numeric | Specifies the identifier of the static control used for displaying the current drive and directory. If the value of this parameter is zero, DLGDIRLISTCOMBOBOX assumes that no such control is present.
DLL-WS | windows.cpy | Specifies the attributes of the filenames to be displayed. This parameter can be one or more of the following values:
 | Value | Meaning
 | DDL-READWRITE | Read-write data files with no additional attributes.
 | DDL-READONLY | Read-only files.
 | DDL-HIDDEN | Hidden files.
 | DDL-SYSTEM | System files.
 | DDL-DIRECTORY | Directories.
 | DDL-ARCHIVE | Archives.
 | DDL-POSTMSGS | CB-DIR flag. If the CB-DIR flag is set, Windows places the messages generated by DLGDIRLISTCOMBOBOX in the application’s queue; otherwise, they are sent directly to the dialog box procedure.
 | DDL-DRIVES | Drives. If the DDL-DRIVES flag is set, the DDL-EXCLUSIVE flag is set automatically. Therefore, to create a directory listing that includes drives and files, the developer must call DLGDIRLISTCOMBOBOX twice: once with the DDL-DRIVES flag set and once with the flags for the rest of the list.
 | DDL-EXCLUSIVE | Exclusive bit. If the exclusive bit is set, only files of the specified type are listed; otherwise, files of the specified type are listed in addition to normal files.


DLGDIRSELECT

Dialog Windows API Function

The DLGDIRSELECT function retrieves the current selection from a list box. It assumes that the list box has been filled by the DLGDIRLIST function and that the selection is a drive letter, a file, or a directory name.

If the current selection is a directory name or drive letter, DLGDIRSELECT removes the enclosing brackets (and hyphens, for drive letters) so that the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of the PATH-NAME parameter do not change.

The DLGDIRSELECT function does not allow more than one filename to be returned from a list box.

The list box must not be a multiple-selection list box. If it is, this function will not return a zero value and PATH-NAME will remain unchanged.

DLGDIRSELECT sends LB-GETCURSEL and LB-GETTEXT messages to the list box.

Calling Sequence

CALL DLGDIRSELECT USING WIN-RETURN WND-H PATH-NAME LIST-BOX-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the list box.
PATH-NAME | PIC X(260) | Receives the selected path or filename. This field should be 260 bytes long or else the path or filename may be truncated.
LIST-BOX-ID | numeric | Specifies the integer identifier of a list box in the window.


DLGDIRSELECTEX

Dialog Windows API Function

The DLGDIRSELECTEX function retrieves the current selection from a list box. The specified list box should have been filled by the DLGDIRLIST function, and the selection should be a drive letter, a file, or a directory name.

If the current selection is a directory name or drive letter, DLGDIRSELECTEX removes the enclosing square brackets (and hyphens, for drive letters) so that the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of the PATH-NAME parameter does not change.

The DLGDIRSELECTEX function does not allow more than one filename to be returned from a list box.

The list box must not be a multiple-selection list box. If it is, this function will not return a zero value and PATH-NAME will remain unchanged.

DLGDIRSELECTEX sends LB-GETCURSEL and LB-GETTEXT messages. If the current selection is a directory name or drive letter, DLGDIRSELECTEX removes the enclosing square brackets messages to the list box.

Calling Sequence

CALL DLGDIRSELECTEX USING WIN-RETURN WND-H PATH-NAME
PATH-SIZE LISTBOX-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the current list box selection is a directory name. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the list box.
PATH-NAME | PIC X(1) - X(260) | Receives the selected path or filename. This field should be 260 bytes long or else the path or filename may be truncated.
PATH-SIZE | numeric | Specifies the length, in bytes, of the PATH-NAME parameter. This value should not be larger than 260. If this value is zero, the size of the PATH-NAME parameter will be automatically calculated.
LISTBOX-ID | numeric | Specifies the identifier of a list box in the window.


DLGDIRSELECTCOMBOBOX

Dialog Windows API Function

The DLGDIRSELECTCOMBOBOX function retrieves the current selection from the list box of a combo box. It assumes that the list box has been filled by the DLGDIRLISTCOMBOBOX function and that the selection is a drive letter, a file, or a directory name.

The DLGDIRSELECTCOMBOBOX function does not allow more than one selection to be returned from a combo box.

If the current selection is a directory name or drive letter, DLGDIRSELECTCOMBOBOX removes the enclosing brackets (and hyphens, for drive letters) so that the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of buffer pointed to by the PATH-NAME parameter do not change.

Calling Sequence

CALL DLGDIRSELECTCOMBOBOX USING WIN-RETURN WND-H
PATH-NAME COMBOBOX-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the combo box.
PATH-NAME | PIC X(260) | Receives the selected path or filename. This field should be 260 bytes long or else the path or filename may be truncated.
COMBOBOX-ID | numeric | Specifies the identifier of the combo box in the window.


DLGDIRSELECTCOMBOBOXEX

Dialog Windows API Function

The DLGDIRSELECTCOMBOBOXEX function retrieves the current selection from the list box of a combo box. The list box should have been filled by the DLGDIRLISTCOMBOBOX function, and the selection should be a drive letter, a file, or a directory name.

The DLGDIRSELECTCOMBOBOXEX function does not allow more than one filename to be returned from a combo box.

If the current selection is a directory name or drive letter, DLGDIRSELECTCOMBOBOXEX removes the enclosing square brackets (and hyphens, for drive letters) so that the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of the PATH-NAME parameter do not change.

DLGDIRSELECTCOMBOBOXEX sends CB-GETCURSEL and CB-GETLBTEXT messages to the combo box.

Calling Sequence

CALL DLGDIRSELECTCOMBOBOXEX USING WIN-RETURN WND-H
PATH-NAME PATH-SIZE COMBOBOX-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the current combo box selection is a directory name. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the combo box.
PATH-NAME | PIC X(1) - X(260) | Receives the selected path or filename.
PATH-SIZE | numeric | Specifies the length, in bytes, of the PATH-NAME parameter. This value should not be larger than 260. If this value is zero, the size of the PATH-NAME parameter will be automatically calculated.
COMBOBOX-ID | numeric | Specifies the identifier of the combo box in the window.


GETDIALOGBASEUNITS

Dialog Windows API Function

The GETDIALOGBASEUNITS function returns the dialog box base units used by Windows when creating dialog boxes. An application should use these values to calculate the average width of characters in the system font.

The values returned represent dialog box base units before being scaled to dialog box units. The dialog box unit in the x-direction is one-fourth of the width returned by the GETDIALOGBASEUNITS function. The dialog box unit in the y-direction is one-eighth of the height returned by the function.

To use GETDIALOGBASEUNITS to determine the height and width, in pixels, of a control, given the width (x) and height (y) in dialog box units and the return value (LDLGBASEUNITS), use the following formulas:

(x * LOWORD(LDLGBASEUNITS)) / 4

(y * HIWORD(LDLGBASEUNITS)) / 8

To avoid rounding problems, perform the multiplication before the division, in case the dialog box base units are not evenly divisible by four.

Calling Sequence

CALL GETDIALOGBASEUNITS USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The low-order word of the return value contains the width, in pixels, of the current dialog box base-width unit, if the function is successful (this base unit is derived from the system font); the high-order word of the return value contains the height, in pixels. Otherwise, it is zero.


GETDLGCTRLID

Dialog Windows API Function

The GETDLGCTRLID function returns the ID value of a specified child window.

Since top-level windows do not have an identifier, the GETDLGCTRLID function’s return value is invalid if the WND-H parameter identifies a top-level window.

Calling Sequence

CALL GETDLGCTRLID USING CHILD-ID WND-H.

Parameter | Declaration | Description
CHILD-ID | numeric | Specifies the identifier of the control.
WND-H | PIC 9(10) BINARY(8) | The handle of the child window.


GETDLGITEM

Dialog Windows API Function

The GETDLGITEM function retrieves the handle of a control that is specified in the given dialog box.

The GETDLGITEM function can be used with any parent-child window pair. As long as the WND-H parameter identifies a parent window and the child window has a unique identifier (as specified by the MENU parameter in the CREATEWINDOW function that created the child window), GETDLGITEM returns the handle of the child window.

Calling Sequence

CALL GETDLGITEM USING CHILD-H WND-H CONTROL-ID.

Parameter | Declaration | Description
CHILD-H | PIC 9(10) BINARY(8) | The return value is the handle of the specified control if the function is successful. Otherwise, it is zero, indicating either an invalid window handle or a nonexistent control.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the control.
CONTROL-ID | numeric | Specifies the identifier of the control to be retrieved.


GETDLGITEMINT

Dialog Windows API Function

The GETDLGITEMINT function translates the text of a specified control in the dialog box into an integer.

The function retrieves the text of the specified control by sending the control a WM-GETTEXT message. The function translates the retrieved text by stripping any extra spaces at the beginning of the text and then converting decimal digits. The function stops translating when it reaches the end of the text or encounters a nonnumeric character.

If the value of the SIGNED parameter is WIN-TRUE, the GETDLGITEMINT function checks for a minus sign (-) at the beginning of the text and translates the text into a signed number. If value of this parameter is WIN-FALSE, the function creates an unsigned value. GETDLGITEMINT returns zero if the translated number is greater than 32,767 (for signed numbers) or 65,535 (for unsigned numbers). When an error occurs, such as encountering nonnumeric characters and exceeding the given maximum, GETDLGITEMINT copies zero to the TRANSLATED parameter. If there are no errors, TRANSLATED receives a nonzero value. If TRANSLATED is zero, GETDLGITEMINT does not warn about errors.

Calling Sequence

CALL GETDLGITEMINT USING WIN-RETURN WND-H CONTROL-ID
TRANSLATED SIGNED.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the translated value of the item text if the function is successful. Since zero is a valid return value, the TRANSLATED parameter must be used to detect errors. If an application requires a signed return value, it should cast the return value as an int type.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the control.
CONTROL-ID | numeric | Specifies the identifier of the control to be translated.
TRANSLATED | PIC X | The variable that is to receive the translated flag.
SIGNED | windows.cpy | Specifies whether the value to be retrieved is signed. Can be one of the following: WIN-TRUE if the value is signed or WIN-FALSE if the value is unsigned.


GETDLGITEMTEXT

Dialog Windows API Function

The GETDLGITEMTEXT function retrieves the title or text associated with a control in a dialog box.

The GETDLGITEMTEXT function sends a WM-GETTEXT message to the control.

Calling Sequence

CALL GETDLGITEMTEXT USING WIN-RETURN WND-H CONTROL-ID
CONTROL-TEXT MAX-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the number of bytes copied to the buffer if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the control.
CONTROL-ID | numeric | Specifies the identifier of the control whose title or text is to be retrieved.
CONTROL-TEXT | alphanumeric | A buffer that is to receive the control’s text.
MAX-SIZE | numeric | Specifies the maximum length, in bytes, to be copied to the CONTROL-TEXT parameter. If the value of the length exceeds the limit, it is truncated. If this value is zero, the entire size of CONTROL-TEXT will be used.


GETNEXTDLGGROUPITEM

Dialog Windows API Function

The GETNEXTDLGGROUPITEM function searches for the previous (or next) control within a group of controls in a dialog box. A group of controls begins with a control with the WS-GROUP style of the WIN-STYLE parameter and ends with the last control that does not contain a WS-GROUP style.

If the CTRL-H parameter identifies the last control in the group and the value of the DIRECTION parameter is WIN-FALSE, the GETNEXTDLGGROUPITEM function returns the window handle of the first control in the group. If CTRL-H identifies the first control in the group and the value of the DIRECTION parameter is WIN-TRUE, GETNEXTDLGGROUPITEM returns the window handle of the last control in the group.

Calling Sequence

CALL GETNEXTDLGGROUPITEM USING NEXT-H WND-H CTRL-H DIRECTION.

Parameter | Declaration | Description
NEXT-H | PIC 9(10) BINARY(8) | The return value is the window handle of the previous (or next) control in the group, if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be searched.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to be used as the starting point for the search.
DIRECTION | windows.cpy | Specifies how the function is to search the group of controls in the dialog box. If the value of this parameter is WIN-TRUE, the function searches for the previous control in the group. If the value of this parameter is WIN-FALSE, the function searches for the next control in the group.


GETNEXTDLGTABITEM

Dialog Windows API Function

The GETNEXTDLGTABITEM function retrieves the handle of the first control that has the WS-TABSTOP style of the WIN-STYLE parameter that precedes (or follows) the specified control.

Calling Sequence

CALL GETNEXTDLGTABITEM USING NEXT-H WND-H CTRL-H DIRECTION.

Parameter | Declaration | Description
NEXT-H | PIC 9(10) BINARY(8) | The return value is the window handle of the previous (or next) control that has the WS-TABSTOP style, if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be searched.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to be used as the starting point for the search.
DIRECTION | windows.cpy | Specifies how the function is to search the dialog box. If the value of this parameter is WIN-TRUE, the function searches for the previous control in the window. If the value of this parameter is WIN-FALSE, the function searches for the next control in the window.


ISDLGBUTTONCHECKED

Dialog Windows API Function

The ISDLGBUTTONCHECKED function determines whether a button has a check mark next to it and whether a three-state button is grayed, checked, or neither.

The ISDLGBUTTONCHECKED function sends a BM-GETCHECK message to the button.

Calling Sequence

CALL ISDLGBUTTONCHECKED USING WIN-RETURN WND-H BUTTON-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the specified button is checked, zero if it is not, or -1 if the WND-H parameter is invalid. For three-state buttons, the return value is 2 if the button is grayed, 1 if the button is checked, 0 if it is unchecked, or -1 if WND-H is invalid.
WND-H | PIC 9(10) BINARY(8) | The handle of the dialog box that contains the button.
BUTTON-ID | numeric | Specifies the identifier of the button.


SETDLGITEMINT

Dialog Windows API Function

The SETDLGITEMINT function sets the text of a control in a dialog box to the string representation of a specified integer value.

To set new text, SETDLGITEMINT sends a WM-SETTEXT message to the control.

Calling Sequence

CALL SETDLGITEMINT USING WND-H CONTROL-ID VALUE SIGNED.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the control.
CONTROL-ID | numeric | Specifies the identifier of the control to be changed.
VALUE | numeric | Specifies the value used to generate the item text.
SIGNED | windows.cpy | Specifies whether the VALUE parameter is signed or unsigned. If the value of this parameter is WIN-TRUE, VALUE is signed. If the value of this parameter is WIN-TRUE and VALUE is less than zero, a minus sign is placed before the first digit in the string. If the value of this parameter is WIN-FALSE, VALUE is unsigned.


SETDLGITEMTEXT

Dialog Windows API Function

The SETDLGITEMTEXT function sets the title or text of a control in a dialog box.

The SETDLGITEMTEXT function sends a WM-SETTEXT message to the specified control.

Calling Sequence

CALL SETDLGITEMTEXT USING WND-H CONTROL-ID TEXT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the control.
CONTROL-ID | numeric | Specifies the identifier of the control whose title or text is to be set.
TEXT | alphanumeric | The text to be copied to the control.


Font Functions

The Windows API font functions create and retrieve information about fonts. A font is a subset of a particular typeface, which is a set of characters that share a similar fundamental design.

The following table summarizes the font functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
CREATEFONTINDIRECT | Creates a logical font that has the characteristics given in the specified structure.
GETCHARWIDTH | Retrieves the widths of individual characters in a range of consecutive characters from the current font.
GETTEXTMETRICS | Retrieves the metrics for the current font.


CREATEFONTINDIRECT

Font Windows API Function

The CREATEFONTINDIRECT function creates a logical font that has the characteristics given in the specified structure. The font can subsequently be selected as the current font for any device.

The CREATEFONTINDIRECT function creates a logical font that has the characteristics specified in the WIN-LOGFONT structure. When the font is created, the graphics device interface (GDI) font mapper attempts to match the logical font with an existing physical font. If it cannot find an exact match for the logical font, the font mapper provides an alternative whose characteristics match as many of the requested characteristics as possible.

Fonts created by using the CREATEFONTINDIRECT function must be selected out of any device context in which they were used and then removed by using the SENDMESSAGE function.

Calling Sequence

CALL CREATEFONTINDIRECT USING FONT-H WIN-LOGFONT.

Parameter | Declaration | Description
FONT-H | PIC 9(10) BINARY(8) | The return value is the handle of the logical font if the function is successful. Otherwise, it is zero.
WIN-LOGFONT | windows.cpy | A structure, contained in the copy file logfont.cpy called by windows.cpy, which defines the characteristics of the logical font.


GETCHARWIDTH

Font Windows API Function

The GETCHARWIDTH function retrieves the widths of individual characters in a range of consecutive characters in the current font. If a character in the group of consecutive characters does not exist in a particular font, it will be assigned the width value of the default character.

Calling Sequence

CALL GETCHARWIDTH USING WIN-RETURN DC-H FIRSTCHAR LASTCHAR WIDTHS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
DC-H | PIC 9(10) BINARY(8) | The handle of the device context.
FIRSTCHAR | alphanumeric | Specifies the first character in a group of consecutive characters in the current font.
LASTCHAR | alphanumeric | Specifies the last character in a group of consecutive characters in the current font.
WIDTHS | PIC 9(10) BINARY(8) occurs X times | An array that receives the width values for a group of consecutive characters in the current font.


GETTEXTMETRICS

Font Windows API Function

The GETTEXTMETRICS function retrieves the metrics for the current font.

Calling Sequence

CALL GETTEXTMETRICS USING WIN-RETURN DC-H TEXT-METRIC.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
DC-H | PIC 9(10) BINARY(8) | The handle of the device context.
TEXT-METRIC | windows.cpy | Points to the TEXT-METRIC structure that receives the metrics.


Menu Functions

The Windows API menu functions create, modify, and destroy menus.

The following table summarizes the menu functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
APPENDMENU | Appends a new item to the end of a menu.
CHECKMENUITEM | Selects (places a check mark next to) or clears (removes a check mark from) a specified menu item in the given pop-up menu.
CREATEMENU | Creates an empty menu.
CREATEPOPUPMENU | Creates an empty pop-up menu.
DELETEMENU | Deletes an item from a menu.
DESTROYMENU | Destroys a menu and frees any memory that the menu occupied.
DRAWMENUBAR | Redraws the menu bar of the given form.
ENABLEMENUITEM | Enables, disables, or grays (dims) a menu item.
GETMENU | Retrieves the handle of the menu associated with the given form.
GETMENUITEMCOUNT | Determines the number of items in a pop-up or top-level menu.
GETMENUITEMID | Retrieves the identifier for a menu item located at the given position.
GETMENUSTATE | Retrieves the status flags associated with the specified menu item.
GETMENUSTRING | Copies the label of a menu item into a buffer.
GETSUBMENU | Retrieves the handle of a pop-up menu.
GETSYSTEMMENU | Allows the application to access the System (or Control) menu for copying and modification.
HILITEMENUITEM | Highlights or removes the highlighting from a top-level (menu-bar) menu item.
INSERTMENU | Inserts a new menu item into a menu, moving the items down the menu.
ISMENU | Determines whether the given handle is a menu handle.
MODIFYMENU | Changes an existing menu item.
REMOVEMENU | Deletes a menu item with an associated pop-up menu from a menu, but does not destroy the handle of the pop-up menu, allowing the menu to be reused.
SETMENU | Sets the given window's menu to the specified menu.
SETMENUITEMBITMAPS | Associates the given bitmaps with a menu item.
TRACKPOPUPMENU | Displays the given floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu.


APPENDMENU

Menu Windows API Function

The APPENDMENU function appends a new item to the end of a menu. The application can specify the state of the menu values in the MENU-FLAGS parameter. For more information, click here.

Calling Sequence

CALL APPENDMENU USING WIN-RETURN MENU-H MENU-FLAGS
NEWITEM-H NEWITEM.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-STRING TO TRUE.
CALL APPENDMENU USING WIN-RETURN MENU-H MENU-FLAGS NEWITEM-H NEWITEM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be changed.
MENU-FLAGS | windows.cpy | Specifies information about the state of the new item when it is added to the menu. This parameter consists of one or more of the values listed in the Comments section.
NEWITEM-H | numeric or PIC 9(10) BINARY(8) | Specifies either the command line identifier of the new menu item or, if the MENU-FLAGS parameter is set to MF-POPUP, the menu handle of the pop-up menu.
NEWITEM | alphanumeric or numeric | Specifies the content of the new menu item. The interpretation of the NEWITEM-H parameter depends on whether the MENU-FLAGS parameter includes the MF-STRING flag or the MF-BITMAP flag.


Append Menu Comments

APPENDMENU Comments

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DRAWMENUBAR function.

The following groups of flags are mutually exclusive and cannot be used together:

· MF-DISABLED, MF-ENABLED, and MF-GRAYED

· MF-BITMAP and MF-STRING

· MF-MENUBARBREAK and MF-MENUBREAK

· MF-CHECKED and MF-UNCHECKED

The following flags can be set in the MENU-FLAGS parameter:

Value | Meaning
MF-BITMAP | Uses a bitmap as the item. The low-order word of the NEWITEM parameter contains the handle of the bitmap.
MF-CHECKED | Places a check mark next to (that is, selects) the item. If the application has supplied check-mark bitmaps (see SETMENUITEMBITMAPS), setting this flag displays the “check mark on” bitmap next to the menu item.
MF-DISABLED | Disables the menu item so that it cannot be selected, but does not gray it.
MF-ENABLED | Enables the menu item so that it can be selected, and restores it from its grayed state.
MF-GRAYED | Disables the menu item so that it can be selected, and restores it from its grayed state.
MF-MENUBARBREAK | Functions the same as the MF-MENUBREAK flag, except for pop-up menus, where it separates the new column from the old column with a vertical line.
MF-MENUBREAK | Places the item on a new line for static menu-bar items. For pop-up menus, places the item in a new column, with no dividing line between the columns.
MF-POPUP | Specifies that the menu has a pop-up menu associated with it. The NEWITEM-H parameter specifies a handle to a pop-up menu to be associated with the item. This is used for adding either a top-level pop-up menu or adding a hierarchical pop-up menu to a pop-up menu item.
MF-SEPARATOR | Draws a horizontal dividing line. Can be used only in a pop-up menu. This line cannot be grayed, disabled, or highlighted. The NEWITEM and NEWITEM-H parameters are ignored.
MF-STRING | Specifies that the menu item is a character string; that is, the NEWITEM parameter contains a pointer to a null-terminated string for the menu item.
MF-UNCHECKED | Does not place a check mark next to the item (default).


CHECKMENUITEM

Menu Windows API Function

The CHECKMENUITEM function selects (places a check mark next to) or clears (removes a check mark from) a specified menu item in the given pop-up menu.

The ITEM-ID parameter may identify a pop-up menu item as well as a menu item. No special steps are required to select a pop-up menu item.

Top-level menu items cannot have a check.

A pop-up menu item should be selected by position since it does not have a menu-item identifier associated with it.

Calling Sequence

CALL CHECKMENUITEM USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL CHECKMENUITEM USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | Specifies the previous state of the menu item (either MF-CHECKED or MF-UNCHECKED). If the menu item does not exist, the return value is -1.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu containing the item to be checked. If the item is a pop-up menu, MENU-H should be the handle of the pop-up menu, rather than the top-level menu.
ITEM-ID | numeric | Specifies the identifier of the menu item to be checked (selected or cleared).
MENU-FLAGS | windows.cpy | Specifies the action to take. This parameter can have the value MF-CHECKED or MF-UNCHECKED, combined with the MF-BYCOMMAND or MF-BYPOSITION value. These values have the following meanings:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).
 | MF-CHECKED | Places a check mark next to the menu item. If the application has supplied check-mark bitmaps, setting this flag displays the bitmap next to the menu item.
 | MF-UNCHECKED | Does not place a check mark next to the menu item. No check mark is the default condition if neither MF-CHECKED nor MF-UNCHECKED is set.


CREATEMENU

Menu Windows API Function

The CREATEMENU function creates a menu. The menu is initially empty but can be filled with menu items by using the APPENDMENU or INSERTMENU function.

If the menu is not assigned to a window, an application must free system resources associated with the menu before exiting. An application frees menu resources by calling the DESTROYMENU function. Windows automatically frees resources associated with a menu that is assigned to a window.

Calling Sequence

CALL CREATEMENU USING MENU-H.

Parameter | Declaration | Description
MENU-H | PIC 9(10) BINARY(8) | The return value is the handle of the newly created menu if the function is successful. Otherwise, it is zero.


CREATEPOPUPMENU

Menu Windows API Function

The CREATEPOPUPMENU function creates an empty pop-up menu.

An application adds items to the pop-up menu by calling the APPENDMENU and INSERTMENU functions. The application can add the pop-up menu to an existing menu or pop-up menu, or it can display and track selections on the pop-up menu by calling the TRACKPOPUPMENU function.

Before exiting, an application must free system resources associated with a pop-up menu if the menu is not assigned to a window. An application frees a menu by calling the DESTROYMENU function.

Calling Sequence

CALL CREATEPOPUPMENU USING MENU-H.

Parameter | Declaration | Description
MENU-H | PIC 9(10) BINARY(8) | The return value is the handle of the newly created menu if the function is successful. Otherwise, it is zero.


DELETEMENU

Menu Windows API Function

The DELETEMENU function deletes an item from a menu. If the menu item has an associated pop-up menu, DELETEMENU destroys the handle of the pop-up menu and frees the memory used by the pop-up menu.

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DRAWMENUBAR function.

Calling Sequence

CALL DELETEMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL DELETEMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be deleted.
ITEM-ID | numeric | Specifies the menu item to be deleted, as determined by the MENU-FLAGS parameter.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is interpreted. This parameter can be one of the following values:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).


DESTROYMENU

Menu Windows API Function

The DESTROYMENU function destroys a menu and frees any memory that the menu occupied.

Calling Sequence

CALL DESTROYMENU USING WIN-RETURN MENU-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be destroyed.


DRAWMENUBAR

Menu Windows API Function

The DRAWMENUBAR function redraws the menu bar of the given window. If a menu bar is changed after Windows has created the window, an application should call this function to draw the changed menu bar.

Calling Sequence

CALL DRAWMENUBAR USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose menu must be redrawn.


ENABLEMENUITEM

Menu Windows API Function

The ENABLEMENUITEM function enables, disables, or grays (dims) a menu item.

To disable or enable input to a menu bar, see the WM-SYSCOMMAND message.

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application should call the DRAWMENUBAR function.

The CREATEMENU, INSERTMENU, and MODIFYMENU functions can also set the state (enabled, disabled, or grayed) of a menu item.

Using the MF-BYPOSITION menu-flag value requires an application to specify the correct menu handle. If the menu handle of the menu bar is specified, a top-level menu item (an item in the menu bar) is affected. To set the state of an item in a pop-up menu by position, an application must specify the handle of the pop-up menu.

When an application specifies the MF-BYCOMMAND menu-flag value, Windows checks all pop-up menu items that are subordinate to the menu identified by the specified menu handle; therefore, unless duplicate menu items are present, specifying the menu handle of the menu bar is sufficient.

Calling Sequence

CALL ENABLEMENUITEM USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND MF-DISABLED MF-GRAYED TO TRUE.
CALL ENABLEMENUITEM USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is 0 if the menu item was previously disabled, or 1 if the menu item was previously enabled. The condition WIN-FAILURE is TRUE if the menu item does not exist.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be enabled.
ITEM-ID | numeric | Specifies the menu item to be enabled, disabled, or grayed. This parameter can specify pop-up menu items as well as standard menu items. The interpretation of this parameter depends on the value of the MENU-FLAGS parameter.
MENU-FLAGS | windows.cpy | Specifies the action to take. This parameter can be one of the MF-DISABLED, MF-ENABLED, or MF-GRAYED values, combined with MF-BYCOMMAND or MF-BYPOSITION. These values have the following meanings:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier.
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).
 | MF-DISABLED | Disables the menu item so that it cannot be selected, but does not gray (dim) it.
 | MF-ENABLED | Enables the menu item so that it can be selected and restores it from its grayed state.
 | MF-GRAYED | Disables the menu item and grays (dims) it so that it cannot be selected.


GETMENU

Menu Windows API Function

The GETMENU function retrieves the handle of the menu associated with the given window.

Calling Sequence

CALL GETMENU USING MENU-H WND-H.

Parameter | Declaration | Description
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu.
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose menu handle is retrieved.


GETMENUITEMCOUNT

Menu Windows API Function

The GETMENUITEMCOUNT function determines the number of items in a pop-up or top-level menu.

Calling Sequence

CALL GETMENUITEMCOUNT USING WIN-RETURN MENU-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the number of items in the menu if the function is successful. Otherwise, it is -1.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be examined.


GETMENUITEMID

Menu Windows API Function

The GETMENUITEMID function retrieves the identifier for a menu item located at the given position.

Calling Sequence

CALL GETMENUITEMID USING WIN-RETURN MENU-H POS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the identifier of the pop-up menu item if the function is successful. If the MENU-H parameter is 0 or if the specified item is a pop-up menu (as opposed to an item within the pop-up menu), the return value is -1. If the POS parameter corresponds to a SEPARATOR menu item, the return value is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the pop-up menu that contains the item whose identifier is to be retrieved.
POS | numeric | Specifies the zero-based position of the menu item whose identifier is to be retrieved.


GETMENUSTATE

Menu Windows API Function

The GETMENUSTATE function retrieves the status flags associated with the specified menu item. If the menu item is a pop-up menu, this function also returns the number of items in the pop-up menu.

Calling Sequence

CALL GETMENUSTATE USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS , all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL GETMENUSTATE USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is -1 if the specified item does not exist.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu.
ITEM-ID | numeric | Specifies the menu item for which the state is retrieved, as determined by the MENU-FLAGS parameter.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is interpreted. When the MENU-FLAGS parameter is MF-BYCOMMAND, the ITEM-ID parameter specifies the menu-item identifier. When the MENU-FLAGS parameter is MF-BYPOSITION, the ITEM-ID parameter specifies the zero-based position of the menu item. In addition to MF-BYCOMMAND or MF-BYPOSITION, this parameter can also include one of the following values:
 | Value | Meaning
 | MF-BITMAP | Item is a bitmap.
 | MF-CHECKED | Check mark is placed next to item (pop-up menus only).
 | MF-DISABLED | Item is disabled.
 | MF-ENABLED | Item is enabled. Note that the value of this constant is zero; an application should not test against zero for failure when using this value.
 | MF-GRAYED | Item is disabled and grayed.
 | MF-MENUBARBREAK | Same as MF-MENUBREAK, except for pop-up menus, where the new column is separated from the old column by a vertical dividing line.
 | MF-MENUBREAK | Item is placed on a new line (static menus) or in a new column (pop-up menus) without separating columns.
 | MF-SEPARATOR | Horizontal dividing line is drawn (pop-up menus only). This line cannot be enabled, checked, grayed, or highlighted. The ITEM-ID and MENU-FLAGS parameters are ignored.
 | MF-UNCHECKED | Check mark is not placed next to item (default). Note that the value of this constant is zero; an application should not test against zero for failure when using this value.


GETMENUSTRING

Menu Windows API Function

The GETMENUSTRING function copies the label of a menu item into a buffer.

Calling Sequence

CALL GETMENUSTRING USING WIN-RETURN MENU-H ITEM-ID
BUFFER MAX-SIZE MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL GETMENUSTRING USING WIN-RETURN MENU-H ITEM-ID BUFFER MAX-SIZE
MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the returned label, if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu.
ITEM-ID | numeric | Specifies the menu item whose label is to be copied, as determined by the MENU-FLAGS parameter.
BUFFER | alphanumeric | A buffer that will receive the label string.
MAX-SIZE | numeric | Specifies the maximum length, in bytes, of the label string. The label string is truncated if it is longer. If this value is zero, the entire size of the buffer will be used.
MENU-FLAGS | windows.cpy | Specifies the nature of the ITEM-ID parameter. It can be one of the following values:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier.
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).


GETSUBMENU

Menu Windows API Function

The GETSUBMENU function retrieves the handle of a pop-up menu.

Calling Sequence

CALL GETSUBMENU USING POPUP-H MENU-H POS.

Parameter | Declaration | Description
POPUP-H | PIC 9(10) BINARY(8) | The return value is the handle of the given pop-up menu if the function is successful. Otherwise, it is zero indicating that no pop-up menu exists at the given position.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu with the pop-up menu that is to be retrieved.
POS | numeric | Specifies the position in the given menu of the pop-up menu. Position values start at zero (zero-based) for the first menu item. The pop-up menu’s identifier cannot be used in this function.


GETSYSTEMMENU

Menu Windows API Function

The GETSYSTEMMENU function allows the application to access the System (or Control) menu for copying and modifying.

Any window that does not use the GETSYSTEMMENU function returns can be used with the APPENDMENU, INSERTMENU, and MODIFYMENU functions to change the System menu.

The System menu initially contains items identified by various identifier values such as SC-CLOSE, SC-MOVE, and SC-SIZE. Menu items on the System menu send WM-SYSCOMMAND messages. All predefined System-menu items have identifier numbers greater than 0xF000. If an application adds commands to the System menu, it should use identifier numbers less than 0xF000.

Windows automatically grays (dims) items on the standard System menu, depending on the situation.

Calling Sequence

CALL GETSYSTEMMENU USING MENU-H WND-H RESET.

Parameter

Declaration

Description

MENU-H

PIC 9(10) BINARY(8)

The return value is the handle of a copy of the System (or Control) menu, if the RESET parameter is WIN-FALSE. If the value of the RESET parameter is WIN-TRUE, the return value is undefined.

WND-H

PIC 9(10) BINARY(8)

The handle of the window that will own a copy of the System (or Control) menu.

RESET

windows.cpy

Specifies the action to be taken. If the value of this parameter is WIN-FALSE, the GETSYSTEMMENU function returns a handle of a copy of the System (or Control) menu currently in use. This copy is initially identical to the System menu, but it can be modified.

If the value of this parameter is WIN-TRUE, GETSYSTEMMENU resets the System menu back to the Windows default state. The previous System menu, if any, is destroyed and, in this case, the return value is undefined.


HILITEMENUITEM

Menu Windows API Function

The HILITEMENUITEM function highlights or removes the highlighting from a top-level (menu-bar) menu item.

The MF-HILITE and MF-UNHILITE flags can be used only with the HILITEMENUITEM function; they cannot be used with the MODIFYMENU function.

Calling Sequence

CALL HILITEMENUITEM USING WIN-RETURN WND-H MENU-H
ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND MF-HILITE TO TRUE.
CALL HILITEMENUITEM USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that contains the menu.
MENU-H | PIC 9(10) BINARY(8) | The handle of the top-level menu that contains the item to be highlighted.
ITEM-ID | numeric | Specifies the menu item to be highlighted, as determined by the value of the MF-HILITE menu-flag parameter.
MENU-FLAGS | windows.cpy | Specifies whether the menu item is highlighted or the highlight is removed. This parameter can have the value MF-HILITE or MF-UNHILITE, combined with the MF-BYCOMMAND or MF-BYPOSITION value. These values have the following meanings:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).
 | MF-HILITE | Menu item is highlighted. If this value is not given, highlighting is removed from the menu item.
 | MF-UNHILITE | Highlighting is removed from the menu item.


INSERTMENU

Menu Windows API Function

The INSERTMENU function inserts a new menu item into a menu, moving other items down the menu. The function also sets the state of the menu item.

Calling Sequence

CALL INSERTMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS
NEWITEM-H NEWITEM.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYPOSITION TO TRUE.
CALL INSERTMENU USING WIN-RETURN MENU-H POS(ITEM-ID) MENU-FLAGS
NEWITEM-H NEWITEM.

Parameter | Declaration | Description
WIN-RETURN | numeric | If the function is successful, the return value is nonzero. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be changed.
ITEM-ID | numeric | Specifies the menu item before which the new menu item is to be inserted, as determined by whether the MENU-FLAGS parameter is set to MF-BYCOMMAND or MF-BYPOSITION.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is interpreted and information about the state of the new menu item when it is added to the menu. This parameter consists of a combination of one of the following required values and the values listed in the Comments section:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero). If the value of the ITEM-ID parameter is -1, the new menu item is appended to the end of the menu.
NEWITEM-H | numeric or PIC 9(10) BINARY(8) | Specifies either the command line identifier of the new menu item or, if the MENU-FLAGS parameter is set to MF-POPUP, the menu handle of the pop-up menu.
NEWITEM | alphanumeric or numeric | Specifies the contents of the new menu item. If MENU-FLAGS is set to MF-STRING (the default value), this parameter points to a null-terminated string. If MENU-FLAGS is set to MF-BITMAP instead, NEWITEM contains a bitmap handle in its low-order word.


Insert Menu Comments

INSERTMENU Comments

Whenever a menu changes (whether or not the menu is in a window that is displayed), the application must call the DRAWMENUBAR function.

The following groups of flags are mutually exclusive and cannot be used together:

· MF-BYCOMMAND and MF-BYPOSITION

· MF-DISABLED, MF-ENABLED, and MF-GRAYED

· MF-BITMAP, MF-STRING, MF-OWNERDRAW, and MF-SEPARATOR

· MF-MENUBARBREAK and MF-MENUBREAK

· MF-CHECKED and MF-UNCHECKED

The following list describes the flags that may be set in the MENU-FLAGS parameter:

Value | Meaning
MF-BITMAP | Uses a bitmap as the menu item. The low-order word of the NEWITEM parameter contains the handle of the bitmap.
MF-CHECKED | Places a check mark next to (that is, selects) the menu item. If the application has supplied check mark bitmaps (see SETMENUITEMBITMAPS), setting this flag displays the "check mark" bitmap next to the menu item.
MF-DISABLED | Disables the menu item so that it cannot be selected, but does not gray (dim) it.
MF-ENABLED | Enables the menu item so that it can be selected and restores it from its grayed state.
MF-GRAYED | Disables the menu item and grays (dims) it so that it cannot be selected.
MF-MENUBARBREAK | Functions the same as the MF-MENUBREAK flag, except for pop-up menus, where it separates the new column from the old column by using a vertical line.
MF-MENUBREAK | Places the menu item on a new line for static menu-bar items. For pop-up menus, this flag places the menu item in a new column, with no dividing line between the columns.
MF-OWNERDRAW | Specifies that the item is an owner-drawn item. This flag is not recommended for use with WOW Extensions.
MF-POPUP | Specifies that the menu item has a pop-up menu associated with it. The NEWITEM-H parameter specifies a handle of a pop-up menu to be associated with the item. Use this flag to add either a top-level pop-up menu or a hierarchical pop-up menu to a pop-up menu item.
MF-SEPARATOR | Draws a horizontal dividing line. This line cannot be grayed, disabled, or highlighted. You can use this flag in a pop-up menu. The NEWITEM and NEWITEM-H parameters are ignored.
MF-STRING | Specifies that the menu item is a character string; the NEWITEM parameter points to the string of the item.
MF-UNCHECKED | Does not select (that is, place a check mark next to) the menu item. No check mark is the default condition if neither MF-CHECKED nor MF-UNCHECKED is set. If the application has supplied check mark bitmaps (see SETMENUITEMBITMAPS), setting this flag displays the "check mark off" bitmap next to the menu item.


ISMENU

Menu Windows API Function

The ISMENU function determines whether the given handle is a menu handle. An application should use this function only to ensure that a given handle is not a menu handle.

Calling Sequence

CALL ISMENU USING WIN-RETURN MENU-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if the handle is definitely not a menu handle. A nonzero return value does not guarantee that the handle is a menu handle, however; for nonzero return values, the application should conduct further tests to verify the handle.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be tested.


MODIFYMENU

Menu Windows API Function

The MODIFYMENU function changes an existing menu item.

Calling Sequence

CALL MODIFYMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS
NEWITEM-H NEWITEM.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL MODIFYMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS
NEWITEM-H NEWITEM.

Parameter | Declaration | Description
WIN-RETURN | numeric | If the function is successful, the return value is nonzero. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be changed.
ITEM-ID | numeric | Specifies the menu item to change, as determined by the MENU-FLAGS parameter. When the MENU-FLAGS parameter is MF-BYCOMMAND, the ITEM-ID parameter specifies the menu-item identifier. When the MENU-FLAGS parameter is MF-BYPOSITION, the ITEM-ID parameter specifies the zero-based position of the menu item.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is interpreted and information about the changes to be made to the menu item. This parameter consists of a combination of one of the following required values and the values listed in the Comments section:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).
NEWITEM-H | numeric or PIC 9(10) BINARY(8) | Specifies either the command line identifier of the modified menu item or, if MENU-FLAGS is set to MF-POPUP, the menu handle of the pop-up menu.
NEWITEM | alphanumeric or numeric | Specifies the content of the changed menu item. If MENU-FLAGS is set to MF-STRING (the default), NEWITEM is a string. If MENU-FLAGS is set to MF-BITMAP instead, NEWITEM is a bitmap handle.


Modify Menu Comments

MODIFYMENU Comments

If the MODIFYMENU function replaces a pop-up menu associated with the menu item, it destroys the old pop-up menu and frees the memory used by the pop-up menu.

Whenever a menu changes (whether or not it is in a window that is displayed), the application must call DRAWMENUBAR function. Note that to change the attributes of existing menu items, it is much faster to use the CHECKMENUITEM and ENABLEMENUITEM functions.

The following groups of flags are mutually exclusive and cannot be used together:

· MF-BYCOMMAND and MF-BYPOSITION

· MF-DISABLED, MF-ENABLED, and MF-GRAYED

· MF-BITMAP, MF-STRING, and MF-OWNERDRAW

· MF-MENUBARBREAK and MF-MENUBREAK

· MF-CHECKED and MF-UNCHECKED

The following list describes the flags that may be set in the MENU-FLAGS parameter:

Value | Meaning
MF-BITMAP | Uses a bitmap as the menu item. The NEWITEM parameter contains the handle of the bitmap.
MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier. This is the default if neither MF-BYCOMMAND nor MF-POSITION is set.
MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero) to be changed rather than the menu-item identifier.
MF-CHECKED | Places a check mark next to (that is, selects) the menu item. If the application has supplied check mark bitmaps (see SETMENUITEMBITMAPS), setting this flag displays the "check mark" bitmap next to the menu item.
MF-DISABLED | Disables the menu item so that it cannot be selected, but does not gray (dim) it.
MF-ENABLED | Enables the menu item so that it can be selected and restores it from its grayed state.
MF-GRAYED | Disables the menu item and grays (dims) it so that it cannot be selected.
MF-MENUBARBREAK | Functions the same as the MF-MENUBREAK flag, except for pop-up menus, where it separates the new column from the old column with a vertical line.
MF-MENUBREAK | Places the menu item on a new line for static menu-bar items. For pop-up menus, this flag places the menu item in a new column, with no dividing line between the columns.
MF-POPUP | Specifies that the menu item has a pop-up menu associated with it. The NEWITEM-H parameter specifies a handle of a pop-up menu to be associated with the menu item. Use this flag to add either a top-level pop-up menu or a hierarchical pop-up menu to a pop-up menu item.
MF-SEPARATOR | Draws a horizontal dividing line. This line cannot be grayed, disabled, or highlighted. You can use this flag only in a pop-up menu. The NEWITEM and NEWITEM-H parameters are ignored.
MF-STRING | Specifies that the menu item is a character string; the NEWITEM parameter is the string for the menu item.
MF-UNCHECKED | Does not select (that is, place a check mark next to) the menu item. No check mark is the default condition if neither MF-CHECKED nor MF-UNCHECKED is set. If the application has supplied check mark bitmaps (see SETMENUITEMBITMAPS), setting this flag displays the “check - mark off” bitmap next to the menu item.


REMOVEMENU

Menu Windows API Function

The REMOVEMENU function deletes a menu item with an associated pop-up menu from a menu but does not destroy the handle of the pop-up menu, allowing the menu to be reused. Before calling this function, an application should call the GETSUBMENU function to retrieve the pop-up menu handle.

Whenever a menu changes (whether or not it is in a window that is displayed), the application should call the DRAWMENUBAR function.

Calling Sequence

CALL REMOVEMENU USING WIN-RETURN MENU-H
ITEM-ID MENU-FLAGS.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL REMOVEMENU USING WIN-RETURN MENU-H ITEM-ID MENU-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu to be changed.
ITEM-ID | numeric | Specifies the menu item to be removed, as determined by the MENU-FLAGS parameter.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is to be interpreted. This parameter can be one of the following values:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier.
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).


SETMENU

Menu Windows API Function

The SETMENU function sets the given window’s menu to the specified menu.

The SETMENU function causes the window to be redrawn to reflect the menu change.

SETMENU will not destroy a previous menu. An application should call the DESTROYMENU function to accomplish this task.

Calling Sequence

CALL SETMENU USING WIN-RETURN WND-H MENU-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose menu is to be changed.
MENU-H | PIC 9(10) BINARY(8) | The handle of the new menu. If the value of this parameter is zero, the window’s current menu is removed.


SETMENUITEMBITMAPS

Menu Windows API Function

The SETMENUITEMBITMAPS function associates the given bitmaps with a menu item. Whether the menu item is checked or unchecked, Windows displays the appropriate check mark bitmap next to the menu item.

If either the UNCHECKED-BMP-H or the CHECKED-BMP-H parameter is zero, Windows displays nothing next to the menu item for the corresponding attribute. If both parameters are zero, Windows uses the default check mark when the item is checked and removes the check mark when the item is unchecked.

When the menu is destroyed, these bitmaps are not destroyed; the application must destroy them.

Calling Sequence

CALL SETMENUITEMBITMAPS USING WIN-RETURN MENU-H ITEM-ID
MENU-FLAGS UNCHECKED-BMP-H CHECKED-BMP-H.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET MF-BYCOMMAND TO TRUE.
CALL SETMENUITEMBITMAPS USING WIN-RETURN MENU-H ITEM-ID
MENU-FLAGS UNCHECKED-BMP-H CHECKED-BMP-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the menu.
ITEM-ID | numeric | Specifies the menu item to be changed, as determined by the MENU-FLAGS parameter.
MENU-FLAGS | windows.cpy | Specifies how the ITEM-ID parameter is interpreted. This parameter can be one of the following values:
 | Value | Meaning
 | MF-BYCOMMAND | Specifies that the ITEM-ID parameter gives the menu-item identifier (MF-BYCOMMAND is the default).
 | MF-BYPOSITION | Specifies that the ITEM-ID parameter gives the position of the menu item (the first item is at position zero).
UNCHECKED-BMP-H | PIC 9(10) BINARY(8) | The handle of the check mark bitmap to display when the menu item is not checked.
CHECKED-BMP-H | PIC 9(10) BINARY(8) | The handle of the check mark bitmap to display when the menu item is checked.


TRACKPOPUPMENU

Menu Windows API Function

The TRACKPOPUPMENU function displays the given floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu. A floating pop-up menu can appear anywhere on the screen.

Calling Sequence

CALL TRACKPOPUPMENU USING WIN-RETURN MENU-H MENU-FLAGS
X Y RESERVED WND-H RECT.

Note By first initializing the MENU-FLAGS parameter with the statement MOVE ALL 'N' TO MENU-FLAGS, all existing values are unset so that new values can be specified. For example:

MOVE ALL 'N' TO MENU-FLAGS.
SET TPM-CENTERALIGN TO TRUE.
CALL TRACKPOPUPMENU USING WIN-RETURN MENU-H MENU-FLAGS
X Y RESERVED WND-H RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
MENU-H | PIC 9(10) BINARY(8) | The handle of the pop-up menu to be displayed. The application retrieves this handle by calling the CREATEPOPUPMENU function to create a new pop-up menu or by calling the GETSUBMENU function to retrieve the handle of a pop-up menu associated with an existing menu item.
MENU-FLAGS | windows.cpy | Specifies the screen-position and mouse-button flags.
 |  | The screen-position flag can be one of the following:
 | Value | Meaning
 | TPM-CENTERALIGN | Centers the pop-up menu horizontally relative to the coordinate specified by the X parameter.
 | TPM-LEFTALIGN | Positions the pop-up menu so that its left side is aligned with the coordinate specified by the X parameter.
 | TPM-RIGHTALIGN | Positions the pop-up menu so that its right side is aligned with the coordinate specified by the X parameter.
 |  | The mouse-button flag can be one of the following:
 | Value | Meaning
 | TPM-LEFTBUTTON | Causes the pop-up menu to track the left mouse button.
 | TPM-RIGHTBUTTON | Causes the pop-up menu to track the right mouse button instead of the left.
X | numeric | Specifies the horizontal position, in screen coordinates, of the pop-up menu. Depending on the value of the MENU-FLAGS parameter, the menu can be left aligned, right aligned, or centered relative to this position.
Y | numeric | Specifies the vertical position, in screen coordinates, of the top of the menu on the screen.
RESERVED | numeric | Reserved; must be zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that owns the pop-up menu. This window receives all WM-COMMAND messages from the menu. The window will not receive WM-COMMAND messages until TRACKPOPUPMENU returns.
RECT | windows.cpy | A RECT structure that contains the screen coordinates of a rectangle in which the user can click without dismissing the pop-up menu. If the value of this parameter is zero, the pop-up menu is dismissed if the user clicks outside the pop-up menu.


Profile Functions

The Windows API profile functions obtain information from and copy information to a Windows or private (application-specific) initialization file. The Windows initialization file (win.ini) is a special ASCII file that contains entry-value pairs representing runtime options for applications.

The following table summarizes the profile functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
GETPRIVATEPROFILEINT | Returns the value of an integer from an entry within a specified section of the win.ini file.
GETPRIVATEPROFILESECTION | Returns the names of all sections in an initialization file.
GETPRIVATEPROFILESTRING | Returns a character string from the specified section in win.ini.
GETPROFILEINT | Returns the value of an integer from an entry within a specified section of the win.ini file.
GETPROFILESECTION | Returns all the keys and values for the specified section of the win.ini file.
GETPROFILESTRING | Returns the string associated with an entry within the specified section in the win.ini file.
WRITEPRIVATEPROFILESECTION | Replaces the keys and values for the specified section in an initialization file.
WRITEPRIVATEPROFILESTRING | Copies a character-string into the specified section of win.ini.
WRITEPROFILESECTION | Replaces the contents of the specified section in the win.ini file with specified keys and values.
WRITEPROFILESTRING | Copies a character-string into the specified section of win.ini.


GETPRIVATEPROFILEINT

Profile Windows API Function

The GETPRIVATEPROFILEINT function retrieves the value of an integer from an entry within a specified section of a specified initialization file.

The function searches the file for an entry that matches the name specified by the ENTRY parameter under the section heading specified by the SECTION parameter. An integer entry in the initialization file must have the following form:

Example

[section]
entry=value
.
.
.

If the value that corresponds to the entry consists of digits followed by nonnumeric characters, the function returns the value of the digits. For example, the function would return 102 for the line “Entry=102abc”.

The GETPRIVATEPROFILEINT function is not case-dependent, so the strings in the SECTION and ENTRY parameters may contain a combination of uppercase and lowercase letters.

GETPRIVATEPROFILEINT supports hexadecimal notation. When GETPRIVATEPROFILEINT is used to retrieve a negative integer, the value should be cast to an int.

An application can use the GETPROFILEINT function to retrieve an integer value from the win.ini file.

Calling Sequence

CALL GETPRIVATEPROFILEINT USING WIN-RETURN SECTION ENTRY
DEFAULT FILENAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the integer value of the specified entry if the function is successful. It is the value of the DEFAULT parameter if the function does not find the entry. The return value is zero if the value that corresponds to the specified entry is not an integer.
SECTION | alphanumeric | A string containing the section heading in the initialization file.
ENTRY | alphanumeric | A string containing the entry whose value is to be retrieved.
DEFAULT | numeric | Specifies the default value to return if the entry cannot be found in the initialization file. This value must be a positive integer in the range 0 through 32,767 (0x0000 through 0x7FFF).
FILENAME | alphanumeric | A string that names the initialization file. If this parameter does not contain a full path, Windows searches for the file in the Windows directory.


GETPRIVATEPROFILESECTION

Profile Windows API Function

The GETPRIVATEPROFILESECTION function returns all the keys and values for the specified section of an initialization file.

Calling Sequence

CALL GETPRIVATEPROFILESECTION USING WIN-RETURN SECTION
BUFFER BUFFER-SIZE FILENAME [DELIMITER].

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the number of characters copied to the BUFFER parameter. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to BUFFER-SIZE minus two.
SECTION | alphanumeric | A string that specifies the name of the section in the initialization file. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
BUFFER | alphanumeric | A buffer that receives the key name and value pairs associated with the section named by the SECTION parameter. The key names and value pairs are separated by the character specified by the DELIMITER parameter.
BUFFER-SIZE | numeric | Specifies the size, in bytes, of the buffer pointed to by the BUFFER parameter. If this value is zero, the size will be calculated automatically.
FILENAME | alphanumeric | A string that names the initialization file. If this parameter does not contain a full path, Windows searches for the file in the Windows directory.
DELIMITER | alphanumeric | An optional parameter that specifies the character that separates the key names and value pairs. The default value is a semicolon (;).


GETPRIVATEPROFILESTRING

Profile Windows API Function

The GETPRIVATEPROFILESTRING function retrieves a character string from the specified section in the specified initialization file.

GETPRIVATEPROFILESTRING is not case-dependent. Consequently, the strings in the SECTION and ENTRY parameters may contain a combination of uppercase and lowercase letters.

Calling Sequence

CALL GETPRIVATEPROFILESTRING USING WIN-RETURN SECTION ENTRY
DEFAULT BUFFER BUFFER-SIZE FILENAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies length of the string specified in the ENTRY parameter.
SECTION | alphanumeric | A string that specifies the section containing the entry. If this parameter is empty (all spaces), this function copies all section names in the file to the buffer specified by the BUFFER parameter. The section names are separated by a semi-colon (;).
ENTRY | alphanumeric | A string containing the entry whose associated string is to be retrieved. If this value is empty (all spaces), all keys in the section specified by the SECTION parameter are copied to the buffer specified by the BUFFER parameter. The key names are separated by a semi-colon (;).
DEFAULT | alphanumeric | A string that specifies the default value for the given entry if the entry cannot be found in the initialization file. This parameter must never be empty.
BUFFER | alphanumeric | A buffer that receives the character string.
BUFFER-SIZE | numeric | Specifies the size, in bytes, of the buffer pointed to by the BUFFER parameter. If this value is zero, the size will be calculated automatically.
FILENAME | alphanumeric | A string that names the initialization file. If this parameter does not contain a full path, Windows searches for the file in the Windows directory.


GETPROFILEINT

Profile Windows API Function

The GETPROFILEINT function retrieves the value of an integer from an entry within a specified section of the win.ini initialization file.

The GETPROFILEINT function is not case-dependent, so the strings in the SECTION and ENTRY parameters may contain a combination of uppercase and lowercase letters.

GETPROFILEINT supports hexadecimal notation.

An integer entry in the win.ini file must have the following form:

Example

[section]
entry=value
.
.
.

If the value that corresponds to the entry consists of digits followed by nonnumeric characters, the function returns the value of the digits. For example, the function would return 102 for the line “Entry=102abc”.

An application can use the GETPRIVATEPROFILEINT function to retrieve an integer from a specified file.

Calling Sequence

CALL GETPROFILEINT USING WIN-RETURN SECTION ENTRY DEFAULT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the integer value of the string following the specified entry, if the function is successful. The return value is the value of the DEFAULT parameter if the function does not find the entry. The return value is zero if the value that corresponds to the specified entry is not an integer.
SECTION | alphanumeric | A string that specifies the section containing the entry.
ENTRY | alphanumeric | A string containing the entry whose value is to be retrieved.
DEFAULT | numeric | Specifies the default value to return if the entry cannot be found. This value can be an unsigned value in the range 0 through 65,536 or a signed value in the range -32,768 through 32,768.


GETPROFILESECTION

Profile Windows API Function

The GETPROFILESECTION function retrieves all the keys and values for the specified section of the win.ini initialization file.

Calling Sequence

CALL GETPROFILESECTION USING WIN-RETURN SECTION
BUFFER BUFFER-SIZE DELIMITER.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the number of characters copied to the BUFFER parameter. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to BUFFER-SIZE minus two.
SECTION | alphanumeric | A string that specifies name of the section in the win.ini file. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
BUFFER | alphanumeric | A buffer that receives the key name and value pairs associated with the named section. The key names and value pairs are separated by the character specified in the DELIMITER parameter.
BUFFER-SIZE | numeric | Specifies the size, in bytes, of the BUFFER parameter. If this value is zero, the size will be computed automatically.
DELIMITER | alphanumeric | An optional parameter that specifies the character that separates the key names and value pairs. The default value is a semicolon (;).


GETPROFILESTRING

Profile Windows API Function

The GETPROFILESTRING function retrieves the string associated with a key within the specified section in the win.ini initialization file.

GETPROFILESTRING is not case-dependent. Consequently, the strings in the SECTION and ENTRY parameters may contain a combination of uppercase and lowercase letters.

A string entry in the win.ini file must have the following form:

Example

[section]
entry=string
.
.
.

An application can use the GETPRIVATEPROFILESTRING function to retrieve a string from a specified file.

Calling Sequence

CALL GETPROFILESTRING USING WIN-RETURN SECTION ENTRY DEFAULT
BUFFER and BUFFER-SIZE.

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is the length of the string specified in the ENTRY parameter.

SECTION

alphanumeric

A string that specifies the section containing the entry. If this parameter is empty (all spaces), this function copies all section names in the file to the buffer specified by the BUFFER parameter. The section names are separated by a semi-colon (;).

ENTRY

alphanumeric

A string containing the entry whose associated string is to be retrieved. If this value is empty (all spaces), all keys in the section specified by the SECTION parameter are copied to the buffer specified by the BUFFER parameter. The key names are separated by a semi-colon (;).

If the string associated with ENTRY is enclosed in single or double quotation marks, the marks are discarded when GETPROFILESTRING returns the string.

DEFAULT

alphanumeric

The default value for the given entry if the value specified in the ENTRY parameter cannot be found in the initialization file. This parameter must never be empty.

BUFFER

alphanumeric

The buffer that will receive the character string.

BUFFER-SIZE

numeric

Specifies the size, in bytes, of the BUFFER parameter. If this value is zero, the size will be computed automatically.


WRITEPRIVATEPROFILESECTION

Profile Windows API Function

The WRITEPRIVATEPROFILESECTION function replaces the keys and values for the specified section of an initialization file.

To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. If that filename is specified and the other three parameters are blank, Windows flushes the cache.

Sections in the initialization file have the following form:

Example

[section]
key=string
.
.
.

Calling Sequence

CALL WRITEPRIVATEPROFILESECTION USING WIN-RETURN
SECTION BUFFER FILENAME [DELIMITER].

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
SECTION | alphanumeric | A string that specifies the section in which data is written. This section is typically the name of the calling application. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
BUFFER | alphanumeric | A string containing the new key names and associated values that are to be written to the named section. This string is limited to 65,535 bytes.
FILENAME | alphanumeric | A string that names the initialization file. If this parameter does not contain a full path for the file, the function searches the Windows directory for the file. If the file does not exist and FILENAME does not contain a full path, the function creates the file in the Windows directory. If the file exists and was created using Unicode characters, the function writes Unicode characters to the file. Otherwise, the function creates a file using ANSI characters.
DELIMITER | alphanumeric | An optional parameter that specifies the character that separates the key names and value pairs. The default value is a semicolon (;).


WRITEPRIVATEPROFILESTRING

Profile Windows API Function

The WRITEPRIVATEPROFILESTRING function copies a character string into the specified section of the specified initialization file.

To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. If that filename is specified and the other three parameters are blank, Windows flushes the cache.

Sections in the initialization file have the following form:

Example

[section]
entry=string
.
.
.

If FILENAME does not contain a fully qualified path and filename for the file, WRITEPRIVATEPROFILESTRING searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.

If FILENAME contains a fully qualified path and filename and the file does not exist, this function creates the file. The specified directory must already exist.

An application should use a private (application-specific) initialization file to record information that affects only that application. This improves the performance of both the application and Windows itself by reducing the amount of information that Windows must read when it accesses the initialization file. The exception to this is that device drivers should use the SYSTEM.INI file, to reduce the number of initialization files Windows must open and read during the startup process.

An application can use the WRITEPROFILESTRING function to add a string to the win.ini file.

Calling Sequence

CALL WRITEPRIVATEPROFILESTRING USING WIN-RETURN
SECTION ENTRY STRING FILENAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
SECTION | alphanumeric | A string that specifies the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
ENTRY | alphanumeric | A string containing the entry to be associated with the string. If the entry does not exist in the specified section, it is created. If the value of this parameter is blank, the entire section, including all entries within the section, is deleted.
STRING | alphanumeric | A string to be written to the file. If the value of this parameter is blank, the entry specified by the ENTRY parameter is deleted.
FILENAME | alphanumeric | A string that names the initialization file.


WRITEPROFILESECTION

Profile Windows API Function

The WRITEPROFILESECTION function replaces the contents of the specified section in the Windows initialization file, win.ini, with specified keys and values. If win.ini uses Unicode characters, the function writes Unicode characters to the file. Otherwise, the function writes ANSI characters.

The WRITEPROFILESECTION function deletes the existing keys and values for the named section and inserts the key names and values in the buffer specified by the BUFFER parameter. The function does not attempt to correlate old and new key names; if the new names appear in a different order from the old names, any comments associated with preexisting keys and values in the initialization file will probably be associated with incorrect keys and values.

This operation is atomic; no other operations that read from or write to the initialization file are allowed while the information is being written.

Windows keeps a cached version of win.ini to improve performance. If all three parameters are blank, Windows flushes the cache.

Sections in the win.ini initialization file have the following form:

Example

[section]
key=string
.
.
.

Calling Sequence

CALL WRITEPROFILESTRING USING WIN-RETURN SECTION
BUFFER [DELIMITER].

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
SECTION | alphanumeric | A string that specifies the name of the section. This section is typically the name of the calling application. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
BUFFER | alphanumeric | A buffer containing the new key names and associated values that are to be written to the section named by the SECTION parameter. This string is limited to 65,535 bytes.
DELIMITER | alphanumeric | An optional parameter that specifies the character that separates the key names and value pairs. The default value is a semicolon (;).


WRITEPROFILESTRING

Profile Windows API Function

The WRITEPROFILESTRING function copies a string into the specified section of the Windows initialization file, win.ini.

Windows keeps a cached version of win.ini to improve performance. If all three parameters are blank, Windows flushes the cache.

Sections in the win.ini initialization file have the following form:

Example

[section]
entry=string
.
.
.

Calling Sequence

CALL WRITEPROFILESTRING USING WIN-RETURN SECTION
ENTRY STRING.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
SECTION | alphanumeric | A string that specifies the section to which the string is to be copied. If the section does not exist, it is created. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
ENTRY | alphanumeric | A string containing the entry to be associated with the string. If the entry does not exist in the specified section, it is created. If the value of this parameter is blank, the entire section, including all entries within the section, is deleted.
STRING | alphanumeric | A string to be written to the file. If the value of this parameter is blank, the entry specified by the ENTRY parameter is deleted.


Scroll Bar Functions

The Windows API scroll bar functions control the window’s scroll bars or the scroll bar controls.

The following table summarizes the scroll bar functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
GETSCROLLPOS | Retrieves the current position of the scroll box (thumb) of a scroll bar.
GETSCROLLRANGE | Retrieves the current minimum and maximum scroll bar positions for the scroll bar.
SETSCROLLPOS | Sets the position of a scroll box (thumb) and, if requested, redraws the scroll bar to reflect the new position of the scroll bar.
SETSCROLLRANGE | Sets minimum and maximum position values for the scroll bar.
SHOWSCROLLBAR | Shows or hides a scroll bar.


GETSCROLLPOS

Scroll Bar Windows API Function

The GETSCROLLPOS function retrieves the current position of the scroll box (thumb) of a scroll bar. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 0 through 100 and the scroll box is in the middle of the bar, the current position is 50.

Calling Sequence

CALL GETSCROLLPOS USING WIN-RETURN WND-H SB-FN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the current position of the scroll box in the scroll bar, if the function is successful. Otherwise, it is zero, indicating that the WND-H parameter is invalid or that the window does not have a scroll bar.
WND-H | PIC 9(10) BINARY(8) | The handle of a window that has standard scroll bars or a scroll bar control, depending on the value of the SB-FN parameter.
SB-FN | numeric | Specifies the scroll bar to examine. It can be one of the following values:
 | Value | Meaning
 | SB-CTL | Retrieves the position of a scroll bar control. In this case, the WND-H parameter must be the window handle of a scroll bar control.
 | SB-HORZ | Retrieves the position of a window’s horizontal scroll bar.
 | SB-VERT | Retrieves the position of a window’s vertical scroll bar.


GETSCROLLRANGE

Scroll Bar Windows API Function

The GETSCROLLRANGE function retrieves the current minimum and maximum scroll bar positions for the given scroll bar.

If the given window does not have standard scroll bars or is not a scroll bar control, the GETSCROLLRANGE function copies zero to the MINPOS and MAXPOS parameters.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both values are zero).

Calling Sequence

CALL GETSCROLLRANGE USING WND-H SB-FN MINPOS MAXPOS.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of a window that has standard scroll bars or a scroll bar control, depending on the value of the SB-FN parameter.
SB-FN | numeric | Specifies which scroll bar to retrieve. This parameter can be one of the following values:
 | Value | Meaning
 | SB-CTL | Retrieves the position of a scroll bar control; in this case, the WND-H parameter must be the handle of a scroll bar control.
 | SB-HORZ | Retrieves the position of a window’s horizontal scroll bar.
 | SB-VERT | Retrieves the position of a window’s vertical scroll bar.
MINPOS | PIC 9(10) BINARY(8) | The variable that receives the minimum position.
MAXPOS | PIC 9(10) BINARY(8) | The variable that receives the maximum position.


SETSCROLLPOS

Scroll Bar Windows API Function

The SETSCROLLPOS function sets the position of a scroll box (thumb) and, if requested, redraws the scroll bar to reflect the new position of the scroll box.

Setting the value of the REPAINT parameter to WIN-FALSE is useful whenever the scroll bar will be redrawn by a subsequent call to another function.

Calling Sequence

CALL SETSCROLLPOS USING WIN-RETURN WND-H SB-TYPE POS REPAINT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the previous position of the scroll box, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose scroll bar is to be set.
SB-TYPE | numeric | Specifies the scroll bar to be set. This parameter can be one of the following values:
 | Value | Meaning
 | SB-CTL | Sets the position of the scroll box in a scroll bar. In this case, the WND-H parameter must be the handle of a scroll bar.
 | SB-HORZ | Sets the position of the scroll box in a window’s horizontal scroll bar.
 | SB-VERT | Sets the position of the scroll box in a window's vertical scroll bar.
POS | numeric | Specifies the new position of the scroll box. It must be within the scrolling range.
REPAINT | numeric | Specifies whether the scroll bar should be repainted to reflect the new scroll box position. If the value of this parameter is WIN-TRUE, the scroll bar is repainted. If the value of this parameter is WIN-FALSE, the scroll bar is not repainted.


SETSCROLLRANGE

Scroll Bar Windows API Function

The SETSCROLLRANGE function sets minimum and maximum position values for the given scroll bar. It can also be used to hide or show standard scroll bars.

An application should not call this function to hide a scroll bar while processing a scroll-bar event.

If the call to SETSCROLLRANGE immediately follows the call to the SETSCROLLPOS function, the REPAINT parameter in SETSCROLLPOS should be zero, to prevent the scroll bar from being drawn twice.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both the MIN and MAX values are zero). The difference between the values specified by the MIN and MAX parameters must not be greater than 32,767.

Calling Sequence

CALL SETSCROLLRANGE USING WND-H SB-TYPE MIN MAX REPAINT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of a window or a scroll bar, depending on the value of the SB-TYPE parameter.
SB-TYPE | numeric | Specifies the scroll bar to be set. This parameter can be one of the following values:
 | Value | Meaning
 | SB-CTL | Sets the range of a scroll bar. In this case, the WND-H parameter must be the handle of a scroll bar.
 | SB-HORZ | Sets the range of a window’s horizontal scroll bar.
 | SB-VERT | Sets the range of a window’s vertical scroll bar.
MIN | numeric | Specifies the minimum scrolling position.
MAX | numeric | Specifies the maximum scrolling position.
REPAINT | numeric | Specifies whether the scroll bar should be repainted to reflect the change. If the value of this parameter is WIN-TRUE, the scroll bar is repainted. If the value of this parameter is WIN-FALSE, the scroll bar is not repainted.


SHOWSCROLLBAR

Scroll Bar Windows API Function

The SHOWSCROLLBAR function shows or hides a scroll bar.

An application should not call this function to hide a scroll bar while processing a scroll-bar notification message.

Calling Sequence

CALL SHOWSCROLLBAR USING WND-H SB-TYPE SHOW.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle a scroll bar or a window that contains a scroll bar in its non-client area, depending on the value of the SB-TYPE parameter. If SB-TYPE is SB-CTL, WND-H identifies a scroll bar. If SB-TYPE is SB-HORZ, SB-VERT, or SB-BOTH, WND-H identifies a window that has a scroll bar in its non-client area.
SB-TYPE | numeric | Specifies whether the scroll bar is a control or part of a window’s non-client area. If the scroll bar is part of the non-client area, SB-TYPE also indicates whether the scroll bar is positioned horizontally, vertically, or both. This parameter can be one of the following values:
 | Value | Meaning
 | SB-BOTH | Specifies the window’s horizontal and vertical scroll bars.
 | SB-CTL | Specifies that the WND-H parameter identifies a scroll bar control.
 | SB-HORZ | Specifies the window’s horizontal scroll bar.
 | SB-VERT | Specifies the window’s vertical scroll bar.
SHOW | numeric | Specifies whether the scroll bar is shown or hidden. If the value of this parameter is WIN-TRUE, the scroll bar is shown; if the value of this parameter is WIN-FALSE, the scroll bar is hidden.


System Functions

The Windows API system functions return information about color and system metrics.

The following table summarizes the system functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
GETASYNCKEYSTATE | Determines whether a key is up or down at the time the function is called, and whether the key was pressed after a previous call to the GETASYNCKEYSTATE function.
GETCURRENTTASK | Returns the handle of the currently running task.
GETCURRENTTIME | Retrieves the number of milliseconds that have elapsed since Windows was started.
GETDOSENVIRONMENT | Returns the environment string of the currently running task.
GETDRIVETYPE | Determines whether a disk drive is removable, fixed, or remote.
GETENVIRONMENTVARIABLE | Retrieves the contents of the specified variable from the environment block of the calling process.
GETINPUTSTATE | Determines whether there are mouse clicks or keyboard events in the system queue that require processing.
GETKEYBOARDSTATE | Copies the status of the 256 virtual-keyboard keys to the specified buffer.
GETKEYBOARDTYPE | Retrieves information about the current keyboard.
GETKEYNAMETEXT | Retrieves a string that represents the name of the key.
GETKEYSTATE | Retrieves the state of the specified virtual key.
GETNEARESTCOLOR | Retrieves the solid color that best matches a specified logical color; the given device must be able to represent this solid color.
GETSYSCOLOR | Retrieves the current color of the specified display element.
GETSYSTEMDIRECTORY | Retrieves the path of the Windows system directory.
GETSYSTEMMETRICS | Retrieves information about the system metrics.
GETTEMPFILENAME | Creates a temporary filename of the following form: drive:\path\prefixuuuu.tmp.
GETTEMPPATH | Retrieves the path of the Windows directory designated for temporary files.
GETVERSION | Returns the current version numbers of the Windows and MS-DOS operating systems. Note that this function has been superseded by GETVERSIONEX.
GETVERSIONEX | Obtains extended information about the version of the operating system that is currently running. Note that this function supersedes GETVERSION.
GETWINDOWSDIRECTORY | Retrieves the path of the Windows directory.
HTMLHELP | Starts the Windows HTML Help system.
KILLTIMER | Removes the specified timer.
MESSAGEBEEP | Generates a waveform sound (beep) corresponding to a given system alert level.
MESSAGEBOX | Creates, displays, and operates a message-box window with the given text and title.
RELEASECAPTURE | Releases the mouse input and restores normal input processing.
SETCAPTURE | Causes the mouse input to be sent to the specified window.
SETENVIRONMENTVARIABLE | Sets the contents of the specified environment variable for the current process.
SETKEYBOARDSTATE | Copies a 256-byte array of keyboard key states into the Window’s keyboard-state table.
SETLOCALEMONETARY | Sets the information about monetary formatting for the current program locality; that is, the country and/or region and language of the host operating system.
SETLOCALENUMERIC | Sets the information about numeric formatting for the current program locality; that is, the country/region and language of the host operating system. Numeric formatting information includes decimal-point character, thousands separator, and the size of each group of digits in non-monetary quantities.
SETTIMER | Installs a system timer.
WINEXEC | Runs the specified application.
WINHELP | Runs Windows Help application (winhelp.exe) and passes optional data indicating the nature of the help requested by the application.


GETASYNCKEYSTATE

System Windows API Function

The GETASYNCKEYSTATE function determines whether a key is up or down at the time the function is called and whether the key was pressed after a previous call to the GETASYNCKEYSTATE function.

If VK-LBUTTON or VK-RBUTTON is specified in the VKEY parameter, this function returns the state of the physical left or right mouse button.

Calling Sequence

CALL GETASYNCKEYSTATE USING WIN-RETURN VKEY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies whether the key was pressed since the last call to the GETASYNCKEYSTATE function and whether the key is currently up or down. If WIN-KEY-DOWN is TRUE, the key is down, and if WIN-PRESSED-SINCE-LAST is TRUE, the key was pressed after a preceding GETASYNCKEYSTATE call. WIN-KEY-DOWN and WIN-PRESSED-SINCE-LAST are defined in windows.cpy.
VKEY | PIC 9(10) BINARY(8) or numeric literal or one of the WIN-VIRTUAL-KEY-CODES values in windows.cpy | Specifies one of 256 possible virtual-key codes.


GETCURRENTTASK

System Windows API Function

The GETCURRENTTASK function retrieves the handle of the current (running) task.

Calling Sequence

CALL GETCURRENTTASK USING TASK-H.

Parameter | Declaration | Description
TASK-H | PIC 9(10) BINARY(8) | The return value is a handle of the current task if the function is successful. Otherwise, it is zero.


GETCURRENTTIME

System Windows API Function

The GETCURRENTTIME function retrieves the number of milliseconds that have elapsed since Windows was started.

Calling Sequence

CALL GETCURRENTTIME USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of milliseconds that have elapsed since Windows was started.


GETDOSENVIRONMENT

System Windows API Function

The GETDOSENVIRONMENT function returns the environment string of the current (running) task.

Calling Sequence

CALL GETDOSENVIRONMENT USING ENV-VALUE.

Parameter | Declaration | Description
ENV-VALUE | alphanumeric | Contains a copy of the environment string of the current task.


GETDRIVETYPE

System Windows API Function

The GETDRIVETYPE function determines whether a disk drive is removable, fixed, or remote.

Calling Sequence

CALL GETDRIVETYPE USING WIN-RETURN ROOTPATHNAME.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The type of drive. Possible values are declared as 78-level descriptions under “DRIVE-TYPES” in windows.cpy.
ROOTPATHNAME | alphanumeric | Specifies the root directory of the disk (including trailing backslash).


GETENVIRONMENTVARIABLE

System Windows API Function

The GETENVIRONMENTVARIABLE function gets the contents of the specified environment variable for the current process.

Note This function has no effect on the system environment variables or the environment variables of other processes.

Calling Sequence

CALL GETENVIRONMENTVARIABLE USING WIN-RETURN ENV-NAME ENV-BUFFER
ENV-BUFFER-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length of the environment variable.
ENV-NAME | alphanumeric | A string that specifies the name of the environment variable. The operating system creates the environment variable if it does not exist and the VALUE parameter is not blank.
ENV-BUFFER | alphanumeric | A buffer that specifies the contents of the environment variable. An environment variable has a maximum size limit of 32,767 characters, including the trailing null terminator.
ENV-BUFFER-SIZE | alphanumeric | Specifies the size, in characters, of the buffer pointed to by the BUFFER parameter.


GETINPUTSTATE

System Windows API Function

The GETINPUTSTATE function determines whether there are mouse clicks or keyboard events in the system queue that require processing. Keyboard events occur when a user presses one or more keys. The system queue is the location in which Windows stores mouse and keyboard events.

Calling Sequence

CALL GETINPUTSTATE USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function detects a mouse click or keyboard event in the system. Otherwise, it is zero.


GETKEYBOARDSTATE

System Windows API Function

The GETKEYBOARDSTATE function copies the status of the 256 virtual-keyboard keys to the specified buffer.

An application calls the GETKEYBOARDSTATE function in response to a keyboard-input message. This function retrieves the state of the keyboard at the time the input message was generated.

If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A toggle key, such as the Caps Lock key, is toggled if it has been pressed an odd number of times since the system was started. The key is untoggled if the low-order bit is 0.

Calling Sequence

CALL GETKEYBOARDSTATE USING KEYSTATE.

Parameter | Declaration | Description
KEYSTATE | PIC X(256) | A 256-byte buffer that will receive the virtual-key codes.


GETKEYBOARDTYPE

System Windows API Function

The GETKEYBOARDTYPE function retrieves information about the current keyboard. Multiple parameters can be specified.

The subtype is an OEM-dependent value. The subtype may be one of the following values:

Values | Meaning
1 | IBM PC/XT or compatible (83-key) keyboard
2 | Olivetti “ICO” (102-key) keyboard
3 | IBM AT (84-key) or similar keyboard
4 | IBM Enhanced (101- or 102-key) keyboard
5 | Nokia 1050 and similar keyboards
6 | Nokia 9140 and similar keyboards
7 | Japanese keyboard

The keyboard driver provides the GETKEYBOARDTYPE function. An application using this function must include the following information in its module-definition (.DEF) file:

IMPORTS
KEYBOARD.GETKEYBOARDTYPE

The application can also determine the number of function keys on a keyboard from the keyboard type. The number of function keys for each keyboard type follows:

Type | Number of function keys
1 | 10
2 | 12 (sometimes 18)
3 | 10
4 | 12
5 | 10
6 | 24
7 | This value is hardware-dependent and must be specified by the OEM.

Calling Sequence

CALL GETKEYBOARDTYPE USING WIN-RETURN KEYBINFO.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the requested information if the function is successful. Otherwise, it is zero.
KEYBINFO | numeric | Determines the type of keyboard information to be retrieved. This parameter can be one of the following values:
 | Value | Meaning
 | 0 | Retrieves the keyboard type.
 | 1 | Retrieves the keyboard subtype.
 | 2 | Retrieves the number of function keys on the keyboard.


GETKEYNAMETEXT

System Windows API Function

The GETKEYNAMETEXT function retrieves a string that represents the name of the key.

The format of the key-name string depends on the current keyboard driver. This driver maintains a list of names in the form of character strings for keys with names longer than a single character. The key name is translated, according to the layout of the currently installed keyboard, into the principal language supported by the keyboard driver.

Calling Sequence

CALL GETKEYNAMETEXT USING WIN-RETURN LPARAM BUFFER MAX-LEN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the string copied to the specified buffer, if the function is successful. Otherwise, it is zero.
LPARAM | numeric | Specifies the 32-bit parameter of the keyboard message such as WM-KEYDOWN to be processed. The GETKEYNAMETEXT function interprets the following portions of LPARAM:
 | Bits | Meaning
 | 16 - 23 | Character scan code.
 | 24 | Extended bit. Distinguishes some keys on an enhanced keyboard.
 | 25 | “Don’t care” bit. The application calling this function sets this bit to indicate that the function should not distinguish between left and right CTRL and SHIFT keys, for example.
BUFFER | alphanumeric | A buffer that will receive the key name.
MAX-LEN | numeric | Specifies the maximum length, in bytes, of the key name.


GETKEYSTATE

System Windows API Function

The GETKEYSTATE function retrieves the state of the specified virtual key. The state specifies whether the key is up, down, or toggled (on, off -- alternating each time the key is pressed).

An application calls the GETKEYSTATE function in response to a keyboard-input message. This function retrieves the state of the key at the time the input message was generated.

Calling Sequence

CALL GETKEYSTATE USING WIN-RETURN VKEY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the state of the given virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A toggle key, such as the CAPSLOCK key, is toggled if it has been pressed an odd number of times since the system was started. The key is untoggled if the low-order bit is 0.
VKEY | alphanumeric or numeric | Specifies a virtual key. If the requested virtual key is a letter or digit (A through Z, a through z, or 0 through 9), VKEY must be set to the ASCII value of that character. For other keys, it must be a virtual-key code.


GETNEARESTCOLOR

System Windows API Function

The GETNEARESTCOLOR function retrieves the solid color that best matches a specified logical color; the given device must be able to represent this solid color.

Calling Sequence

CALL GETNEARESTCOLOR USING WIN-RETURN DC-H CLR-REF.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies an RGB (red, green, blue) color value that defines the solid color closest to the CLR-REF value that the device can represent.
DC-H | PIC 9(10) BINARY(8) | The handle of the device context.
CLR-REF | numeric | Specifies the color to be matched.


GETSYSCOLOR

System Windows API Function

The GETSYSCOLOR function retrieves the current color of the specified display element. Display elements are the various parts of a window and the Windows display that appear on the system screen.

Calling Sequence

CALL GETSYSCOLOR USING WIN-RETURN DSP-ELEMENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a red, green, blue (RGB) color value for the specified display element, if the function is successful.
DSP-ELEMENT | windows.cpy | Specifies the display element whose color is to be retrieved. This parameter can be one of the following values:
 | Value | Meaning
 | COLOR-3DDKSHADOW | Dark shadow for three-dimensional display elements.
 | COLOR-3DFACE | Face color for three-dimensional display elements and for dialog box backgrounds.
 | COLOR-3DHIGHLIGHT, COLOR-3DHILIGHT, COLOR-BTNHILIGHT | Highlight color for three-dimensional display elements (for edges facing the light source).
 | COLOR-3DLIGHT | Light color for three-dimensional display elements (for edges facing the light source).
 | COLOR-3DSHADOW | Light color for three-dimensional display elements (for edges facing away from the light source).
 | COLOR-ACTIVEBORDER | Active window border.
 | COLOR-ACTIVECAPTION | Active window title.
 | COLOR-APPWORKSPACE | Background color of multiple document interface (MDI) applications.
 | COLOR-BACKGROUND, COLOR-DESKTOP | Desktop.
 | COLOR-BTNFACE | Face shading on push buttons.
 | COLOR-BTNHIGHLIGHT | Selected button in a control.
 | COLOR-BTNSHADOW | Edge shading on push buttons.
 | COLOR-BTNTEXT | Text on push buttons.
 | COLOR-CAPTIONTEXT | Text in title bar, size button, scroll-bar arrow button.
 | COLOR-GRADIENTACTIVECAPTION | Right side color in the color gradient of an active window's title bar. COLOR-ACTIVECAPTION specifies the left side color.
 | COLOR-GRADIENTINACTIVECAPTION | Right side color in the color gradient of an inactive window's title bar. COLOR-INACTIVECAPTION specifies the left side color.
 | COLOR-GRAYTEXT | Grayed (dimmed) text. This color is zero if the current display driver does not support a solid gray color.
 | COLOR-HIGHLIGHT | Background of selected item in a control.
 | COLOR-HIGHLIGHTTEXT | Text of selected item in a control.
 | COLOR-HOTLIGHT | Color for a hot-tracked item. Single-clicking a hot-tracked item executes the item.
 | COLOR-INACTIVEBORDER | Inactive window border.
 | COLOR-INACTIVECAPTION | Inactive window title.
 | COLOR-INACTIVECAPTIONTEXT | Color of text in an inactive title.
 | COLOR-INFOBK | Background color for tooltip controls.
 | COLOR-INFOTEXT | Text color for tooltip controls.
 | COLOR-MENU | Menu background.
 | COLOR-MENUBAR | The background color for the menu bar when menus appear as flat menus. However, COLOR-MENU continues to specify the background color of the menu popup.
 | COLOR-MENUHILIGHT | The color used to highlight menu items when the menu appears as a flat menu. The highlighted menu item is outlined with COLOR-HIGHLIGHT.
 | COLOR-MENUTEXT | Text in menus.
 | COLOR-SCROLLBAR | Scroll-bar gray area.
 | COLOR-WINDOW | Window background.
 | COLOR-WINDOWFRAME | Window frame.
 | COLOR-WINDOWTEXT | Text in windows.


GETSYSTEMDIRECTORY

System Windows API Function

The GETSYSTEMDIRECTORY function retrieves the path of the Windows system directory. The system directory contains such files as Windows, libraries, drivers, and font files.

Applications should not create files in the system directory. If the user is running a shared version of Windows, the application will not have write access to the system directory. Applications should create files only in the directory returned by the GETWINDOWSDIRECTORY function.

The path that this function retrieves does not end with a backslash unless the system directory is the root directory. For example, if the system directory is named WINDOW\SYSTEM on drive C, the path of the system directory retrieved by this function is C:WINDOWS\SYSTEM.

Calling Sequence

CALL GETSYSTEMDIRECTORY USING WIN-RETURN SYSPATH SYSPATH-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the string copied to the SYSPATH parameter. If the return value is greater than the size specified in the SYSPATH-SIZE parameter, the return value is the size of the buffer required to hold the path. The return value is zero if the function fails.
SYSPATH | alphanumeric | The buffer that is to receive the string containing the path of the system directory.
SYSPATH-SIZE | numeric | Specifies the maximum size, in bytes, of the buffer. If this value is zero, the size will be calculated automatically.


GETSYSTEMMETRICS

System Windows API Function

The GETSYSTEMMETRICS function retrieves the system metrics. The system metrics are the widths and heights of the various elements displayed by Windows. GETSYSTEMMETRICS can also return flags that indicate whether the current version of the Windows operating system is a debugging version, whether a mouse is present, or whether the meanings of the left and right mouse buttons have been exchanged. System metrics depend on the type of screen and may vary from screen to screen.

Calling Sequence

CALL GETSYSTEMMETRICS USING WIN-RETURN INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the requested system metric if the function is successful. Otherwise, it is zero.
INDEX | numeric | Specifies the system measurement to be retrieved. All measurements are given in pixels. The system measurement must be one of the following values:
 | Value | Meaning
 | SM-CXBORDER | Width of window frame that cannot be sized.
 | SM-CYBORDER | Height of window frame that cannot be sized.
 | SM-CYCAPTION | Height of window title. This is the title height plus the height of the window frame that cannot be sized (SM-CYBORDER)
 | SM-CXCURSOR | Width of cursor.
 | SM-CYCURSOR | Height of cursor.
 | SM-CXDOUBLECLK | Width of the rectangle around the location of the first click in a double-click sequence. The second click must occur within this rectangle for the system to consider the two clicks a double-click.
 | SM-CYDOUBLECLK | Height of the rectangle around the location of the first click in a double-click sequence. The second click must occur within this rectangle for the system to consider the two clicks a double-click.
 | SM-CXDLGFRAME | Width of frame when window has the WS-DLGFRAME style of the WIN-STYLE parameter.
 | SM-CYDLGFRAME | Height of frame when window has the WS-DLGFRAME style of the WIN-STYLE parameter.
 | SM-CXFRAME | Width of window frame that can be sized.
 | SM-CYFRAME | Height of window frame that can be sized.
 | SM-CXFULLSCREEN | Width of window client area for a full-screen window.
 | SM-CYFULLSCREEN | Height of window client area for a full-screen window (equivalent to the height of the screen minus the height of the window title).
 | SM-CXICON | Width of icon.
 | SM-CYICON | Height of icon.
 | SM-CXICONSPACING | Width of rectangles the system uses to position tiled icons.
 | SM-CYICONSPACING | Height of rectangles the system uses to position tiled icons.
 | SM-CYKANJIWINDOW | Height of Kanji window.
 | SM-CYMENU | Height of single-line menu bar. This is the menu height minus the height of the window frame that cannot be sized (SM-CYBORDER).
 | SM-CXMIN | Minimum width of window.
 | SM-CYMIN | Minimum height of window.
 | SM-CXMINTRACK | Minimum tracking width of window.
 | SM-CYMINTRACK | Minimum tracking height of window.
 | SM-CXSCREEN | Width of screen.
 | SM-CYSCREEN | Height of screen.
 | SM-CXHSCROLL | Width of arrow bitmap on a horizontal scroll bar.
 | SM-CYHSCROLL | Height of arrow bitmap on a horizontal scroll bar.
 | SM-CXVSCROLL | Width of arrow bitmap on a vertical scroll bar.
 | SM-CYVSCROLL | Height of arrow bitmap on a vertical scroll bar.
 | SM-CXSIZE | Width of bitmaps contained in the title bar.
 | SM-CYSIZE | Height of bitmaps contained in the title bar.
 | SM-CXHTHUMB | Width of scroll box (thumb) on horizontal scroll bar.
 | SM-CYVTHUMB | Height of scroll box on vertical scroll bar.
 | SM-DBCSENABLED | Nonzero if current version of Windows uses double-byte characters; otherwise, this value returns zero.
 | SM-DEBUG | Nonzero if the Windows version is a debugging version.
 | SM-MENUDROPALIGNMENT | Alignment of pop-up menus. If this value is zero, the left side of a pop-up menu is aligned with the left side of the corresponding menu-bar item. If this value is nonzero, the left side of a pop-up menu is aligned with the right side of the corresponding menu-bar item.
 | SM-MOUSEPRESENT | Nonzero if the mouse hardware is installed.
 | SM-PENWINDOWS | Handle of the Pen Windows dynamic-link library (DLL) if Pen Windows is installed.
 | SM-SWAPBUTTON | Nonzero if the left and right mouse buttons are swapped.


GETTEMPFILENAME

System Windows API Function

The GETTEMPFILENAME function creates a temporary filename of the following form:

Example

drive:\path\prefixuuuu.TMP

The following list describes the filename syntax:

Element | Description
Drive | Drive letter specified by the DRIVELETTER parameter.
Path | Path of the temporary file (either the Windows directory or the directory specified in the TEMP environment variable).
Prefix | All the letters (up to the first three) of the string pointed to by the PREFIXSTRING.
uuuu | Hexadecimal value of the number specified by the UNIQUE parameter.

Temporary files created with this function are not automatically deleted when Windows shuts down.

The GETTEMPFILENAME function uses the suggested drive letter for creating the temporary filename, except in the following cases:

· If a hard disk is present, GETTEMPFILENAME always uses the drive letter of the first hard disk.

· If, however, a TEMP environment variable is defined and its value begins with a drive letter, that drive letter is used.

If the TF-FORCEDRIVE bit of the DRIVELETTER parameter is set, the preceding exceptions do not apply. The temporary filename will always be created in the current directory of the drive specified by DRIVELETTER, regardless of the presence of a hard disk or the TEMP environment variable.

If the UNIQUE parameter is zero, GETTEMPFILENAME attempts to form a unique number based on the current system time. If a file with the resulting filename exists, the number is increased by one and the test for existence is repeated. This continues until a unique filename is found; GETTEMPFILENAME then creates a file by that name and closes it. No attempt is made to create and open the file when UNIQUE is nonzero.

Calling Sequence

CALL GETTEMPFILENAME USING WIN-RETURN DRIVELETTER
PREFIXSTRING UNIQUE TEMPFILENAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies a unique numeric value used in the temporary filename. If the UNIQUE parameter is nonzero, the return value specifies this same number.
DRIVELETTER | alphanumeric | Specifies the suggested drive for the temporary filename. If the value of this parameter is zero, Windows uses the current default drive.
PREFIXSTRING | alphanumeric | A string to be used as the temporary filename prefix. This string must consist of characters in the OEM character set.
UNIQUE | numeric | Specifies an unsigned integer. If the value of this parameter is nonzero, it will be appended to the temporary filename. If the value of this parameter is zero, Windows uses the current system time to create a number to append to the filename.
TEMPFILENAME | PIC X(144) | The buffer that will receive the temporary filename. This string consists of characters in the OEM character set. This buffer should be at least 144 bytes in length to allow sufficient room for the path.


GETTEMPPATH

System Windows API Function

The GETTEMPPATH function retrieves the path of the Windows directory designated for temporary files.

Calling Sequence

CALL GETTEMPPATH USING WIN-RETURN TEMPPATH-SIZE TEMPPATH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value receives the length of TEMPPATH, not including the terminating null character. If the return value is greater than TEMPPATH-SIZE, the return value is the size of the buffer required to hold the path. A value of zero indicates an error.
TEMPPATH-SIZE | numeric | Specifies either the length of the item to return in TEMPPATH or zero to use the size of the COBOL data item TEMPPATH.
TEMPPATH | alphanumeric | Receives the null-terminated string specifying the temporary file path. The returned string ends with a backslash.


GETVERSION

System Windows API Function

Note This function has been superseded by GETVERSIONEX.

The GETVERSION function retrieves the current version numbers of the Windows and MS-DOS operating systems.

The low-order word of the return value contains the version of Windows, if the function is successful. The high-order byte contains the minor version (revision) number as a two-digit decimal number. For example, in Windows 3.1, the minor version number is 10. The low-order byte contains the major version number.

The high-order word contains the version of MS-DOS, if the function is successful. The high-order byte contains the major version; the low-order byte contains the minor version (revision) number.

Calling Sequence

CALL GETVERSION USING WIN-RETURN.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the major and minor version numbers of Windows and of MS-DOS.


GETVERSIONEX

System Windows API Function

The GETVERSIONEX function obtains extended information about the version of the operating system that is currently running.

Note This function supersedes GETVERSION.

Calling Sequence

CALL GETVERSIONEX USING VERSIONEX-WS.

Parameter | Declaration | Description
VERSIONEX-WS | windows.cpy | Specifies operating system version information. The information includes major and minor version numbers, a build number, a platform identifier, and descriptive text about the operating system. Possible values are declared as 78-level descriptions under “VERSIONEX-WS GLOBAL” in windows.cpy.


GETWINDOWSDIRECTORY

System Windows API Function

The GETWINDOWSDIRECTORY function retrieves the path of the Windows directory. The Windows directory contains such files as Windows applications, initialization files, and help files.

The Windows directory is the only directory where an application should create files. If the user is running a shared version of Windows, the Windows directory is the only directory guaranteed private to the user.

The path this function retrieves does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named WINDOWS on drive C, the path retrieved by this function is C:\WINDOWS. If Windows is installed in the root directory of drive C, the path retrieved is C:\.

Calling Sequence

CALL GETWINDOWSDIRECTORY USING WIN-RETURN SYSPATH SYSPATH-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the string copied to the SYSPATH parameter. If the return value is greater than the number specified in the SYSPATH-SIZE parameter, it is the size of the buffer required to hold the path. The return value is zero if the function fails.
SYSPATH | PIC X(144) or larger | The buffer that will receive the string containing the path.
SYSPATH-SIZE | numeric | Specifies the maximum size, in bytes, of the buffer. This value should be set to at least 144 to allow sufficient room in the buffer for the path. If this value is zero, the size of the buffer will be calculated.


HTMLHELP

System Windows API Function

The HTMLHELP function starts the Windows HTML Help system.

Calling Sequence

CALL HTMLHELP USING WIN-RETURN WND-H HELPFILE COMMAND DWDATA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is depends on the value specified by the COMMAND parameter and can be one or both of the following: the handle of the help window or NULL. In some cases, NULL indicates failure; in other cases, NULL indicates that the help window has not yet been created.
WND-H | PIC 9(10) BINARY(8) | The handle of the window requesting help.
HELPFILE | PIC (X) | Specifies the name of the help file to use.
COMMAND | numeric | Specifies the type of help requested. Possible values are declared as 78-level descriptions under “HtmlHelp constants” descriptions in windows.cpy.
DWDATA | numeric | Specifies any data that may be required, based on the value of the COMMAND parameter.


KILLTIMER

System Windows API Function

The KILLTIMER function removes the specified timer. Any pending WM-TIMER messages associated with the timer are removed from the message queue.

Calling Sequence

CALL KILLTIMER USING WIN-RETURN WND-H TIMER-ID.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. It is zero if the KILLTIMER function could not find the specified timer.
WND-H | PIC 9(10) BINARY(8) | The handle of the window associated with the timer to be removed. This must be the same value passed as the WND-H parameter of the SETTIMER function that created the timer.
TIMER-ID | numeric | Specifies the identifier of the timer to be removed. If the application called SETTIMER with the WND-H parameter set to zero, this parameter must be the timer identifier returned by SETTIMER. If the WND-H parameter of SETTIMER was a valid window handle, this parameter must be the value of the TIMER-ID parameter passed to SETTIMER.


MESSAGEBEEP

System Windows API Function

The MESSAGEBEEP function plays a waveform sound corresponding to a given system alert level. The sound for each alert level is identified by an entry in the [sounds] section of the win.ini initialization file.

MESSAGEBEEP returns control to the caller after queuing the sound and plays the sound asynchronously.

If it cannot play the specified alert sound, MESSAGEBEEP attempts to play the system default sound. If it cannot play the system default sound, the function produces a standard beep sound by using the computer speaker.

The user can disable the warning beep by using the Windows Control Panel application, Sounds.

Calling Sequence

CALL MESSAGEBEEP USING ALERT.

Parameter | Declaration | Description
ALERT | numeric | Specifies the alert level. This parameter can be one of the following values:
 | Values | Meaning
 | -1 | Produces a standard beep sound by using the computer speaker.
 | MB-ICONASTERISK | Plays the sound identified by the SystemAsterisk entry in the [sounds] section of win.ini.
 | MB-ICONEXCLAMATION | Plays the sound identified by the SystemExclamation entry in the [sounds] section of win.ini.
 | MB-ICONHAND | Plays the sound identified by the SystemHand entry in the [sounds] section of win.ini.
 | MB-ICONQUESTION | Plays the sound identified by the SystemQuestion entry in the [sounds] section of win.ini.
 | MB-OK | Plays the sound identified by the SystemDefault entry in the [sounds] section of win.ini.


MESSAGEBOX

System Windows API Function

The MESSAGEBOX function creates, displays, and operates a message-box window. The message box contains an application-defined message and title, plus any combination of the predefined icons and push buttons.

When a system-modal message box is created to indicate that the system is low on memory, the strings pointed to by the TEXT and TITLE parameters should not be taken from a resource file, since an attempt to load the resource may fail.

If a message box is created while a dialog box is present, use the handle of the dialog box as the WND-H parameter. The WND-H parameter should not identify a child window, such as a control in a dialog box.

This function is equivalent to the WOWMESSAGEBOX function.

Calling Sequence

CALL MESSAGEBOX USING WIN-RETURN WND-H TEXT TITLE MESSAGE-BOX-FLAGS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is zero if there is not enough memory to create the message box. Otherwise, the return value is one of the following Message-Button-IDs returned by the dialog box:
 | Value | Meaning
 | IDABORT | Abort button was selected.
 | IDCANCEL | Cancel button was selected. If a message box has a Cancel button, the IDCANCEL value will be returned if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.
 | IDIGNORE | Ignore button was selected.
 | IDNO | No button was selected.
 | IDOK | OK button was selected.
 | IDRETRY | Retry button was selected.
 | IDYES | Yes button was selected.
WND-H | PIC 9(10) BINARY(8) | The handle of the parent window of the message box to be created. If the value of this parameter is zero, the message box will have no parent window.
TEXT | alphanumeric | A string containing the message to be displayed.
TITLE | alphanumeric | A string to be used for the dialog box title. If the value of this parameter is zero, the default title Error is used.
MESSAGE-BOX-FLAGS | windows.cpy | Specifies the contents and behavior of the dialog box. This parameter can be one or more of the following values:
 | Value | Meaning
 | MB-ABORTRETRYIGNORE | The message box contains three push buttons: Abort, Retry, and Ignore.
 | MB-APPLMODAL | The user must respond to the message box before continuing work in the window identified by the WND-H parameter. However, the user can move to the windows or other applications and work in those windows. MB-APPLMODAL is the default if neither MB-SYSTEMMODAL nor MB-TASKMODAL is specified.
 | MB-DEFBUTTON1 | The first button is the default. Note that the first button is always the default unless MB-DEFBUTTON2 or MB-DEFBUTTON3 is specified.
 | MB-DEFBUTTON2 | The second button is the default.
 | MB-DEFBUTTON3 | The third button is the default.
 | MB-ICONASTERISK | Same as MB-ICONINFORMATION.
 | MB-ICONEXCLAMATION | An exclamation-point icon appears in the message box.
 | MB-ICONHAND | Same as MB-ICONSTOP.
 | MB-ICONINFORMATION | An icon consisting of a lowercase letter “l” in a circle appears in the message box.
 | MB-ICONQUESTION | A question-mark icon appears in the message box.
 | MB-ICONSTOP | A stop-sign icon appears in the message box.
 | MB-OK | The message box contains one push button: OK.
 | MB-OKCANCEL | The message box contains two push buttons: OK and Cancel.
 | MB-RETRYCANCEL | The message box contains two push buttons: Retry and Cancel.
 | MB-SYSTEMMODAL | All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). This flag has no effect on the user’s ability to interact with windows other than those associated with the parent window specified in the WND-H parameter.
 | MB-TASKMODAL | Same as MB-APPLMODAL, except that all the top-level windows belonging to the current task are disabled if the WND-H parameter is zero. This flag should be used when the calling application or library does not have a window handle available but still needs to prevent input to other windows in the current application without suspending other applications.
 | MB-YESNO | The message box contains two push buttons: Yes and No.
 | MB-YESNOCANCEL | The message box contains three push buttons: Yes, No, and Cancel.


RELEASECAPTURE

System Windows API Function

The RELEASECAPTURE function releases the mouse capture and restores normal input processing. A window with the mouse capture receives all mouse input regardless of the position of the cursor.

An application calls this function after calling the SETCAPTURE function.

Calling Sequence

CALL RELEASECAPTURE.


SETCAPTURE

System Windows API Function

The SETCAPTURE function sets the mouse capture to the specified window. With the mouse capture set to a window, all mouse input is directed to that window, regardless of whether the cursor is over that window. Only one window can have the mouse capture at a time.

When the window no longer requires all mouse input, the application should call the RELEASECAPTURE function so that other windows can receive mouse input.

Calling Sequence

CALL SETCAPTURE USING LASTWND-H WND-H.

Parameter | Declaration | Description
LASTWND-H | PIC 9(10) BINARY(8) | The return value is the handle of the window that previously received all mouse input, if the function is successful. Otherwise, it is zero if there is no such window.
WND-H | PIC 9(10) BINARY(8) | The handle of the window that is to receive all mouse messages.


SETENVIRONMENTVARIABLE

System Windows API Function

The SETENVIRONMENTVARIABLE function sets the contents of the specified environment variable for the current process.

Note This function has no effect on the system environment variables or the environment variables of other processes.

Calling Sequence

CALL SETENVIRONMENTVARIABLE USING NAME VALUE.

Parameter | Declaration | Description
NAME | PIC 9(10) BINARY(8) | A string that specifies the name of the environment variable. The operating system creates the environment variable if it does not exist and the VALUE parameter is not blank.
VALUE | PIC 9(10) BINARY(8) | A string that specifies the contents of the environment variable. An environment variable has a maximum size limit of 32,767 characters, including the trailing null terminator. If this parameter is empty, the variable is deleted from the current process's environment.


SETKEYBOARDSTATE

System Windows API Function

The SETKEYBOARDSTATE function copies a 256-byte array of keyboard key states into the Windows keyboard-state table.

In many cases, an application should call the GETKEYBOARDSTATE function first to initialize the 256-byte array. The application should then change the desired bytes.

SETKEYBOARDSTATE sets the LEDs and BIOS flags for the NUMLOCK, CAPSLOCK, and SCROLL LOCK keys according to the toggle state of the VK-NUMLOCK, VK-CAPITAL, and VK-SCROLL entries of the array.

Calling Sequence

CALL SETKEYBOARDSTATE USING KEYSTATE.

Parameter | Declaration | Description
KEYSTATE | PIC X(256) | Points to a 256-byte array that contains keyboard key states.


SETLOCALEMONETARY

System Windows API Function

The SETLOCALEMONETARY function sets the information about monetary formatting for the current program locality; that is, the country and/or region and language of the host operating system.

Calling Sequence

CALL SETLOCALEMONETARY USING LOCALE GIVING LOCALE-RETURN.

Parameter | Declaration | Description
LOCALE | alphanumeric | A string that refers to the locality (country and language).
LOCALE-RETURN | alphanumeric | A string associated with the country and language specified in LOCALE or spaces if LOCALE is not valid.


SETLOCALENUMERIC

System Windows API Function

The SETLOCALENUMERIC function sets the information about numeric formatting for the current program locality; that is, the country and/or region and language of the host operating system. Numeric formatting information includes decimal-point character, thousands separator, and the size of each group of digits in non-monetary quantities.

Calling Sequence

CALL SETLOCALENUMERIC USING LOCALE GIVING LOCALE-RETURN.

Parameter | Declaration | Description
LOCALE | alphanumeric | A string that refers to the locality (country and language).
LOCALE-RETURN | alphanumeric | A string associated with the country and language specified in LOCALE or spaces if LOCALE is not valid.


SETTIMER

System Windows API Function

The SETTIMER function installs a system timer. A time-out value is specified, and every time a time-out occurs, the system posts a WM-TIMER message to the installing application’s message queue.

Timers are a limited global resource; therefore, it is important that an application check the value returned by the SETTIMER function to verify that a timer is available.

Calling Sequence

CALL SETTIMER USING WIN-RETURN WND-H TIMER-ID TIMEOUT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the identifier of the new timer if WND-H is 0 and the function is successful. An application passes this value to the KILLTIMER function to kill the timer. The return value is nonzero if WND-H is a valid window handle and the function is successful. Otherwise, the return value is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be associated with the timer. The window procedure associated with this window receives the WM-TIMER messages generated by the timer.
TIMER-ID | numeric | Specifies a nonzero timer identifier.
TIMEOUT | numeric | Specifies the time-out value, in milliseconds.


WINEXEC

System Windows API Function

The WINEXEC function runs the specified application.

Calling Sequence

CALL WINEXEC USING INST-H CMDLINE CMDSHOW.

Parameter | Declaration | Description
INST-H | PIC 9(10) BINARY(8) | The return value identifies the instance of the loaded module, if the function is successful. Otherwise, the return value is an error value less than 32. See the Error section.
CMDLINE | PIC X | A null-terminated Windows character string that contains the command line (filename plus optional parameters) for the application to be run. If the string does not contain a path, Windows searches the directories in this order:
 |  | 1. The current directory.
 |  | 2. The Windows directory (the directory containing WIN.COM); the GETWINDOWSDIRECTORY function retrieves the path of this directory.
 |  | 3. The Windows system directory (the directory containing such system files as GDI.EXE); the GETSYSTEMDIRECTORY function retrieves the path of this directory.
 |  | 4. The directory containing the executable file for the current task.
 |  | 5. The directories listed in the PATH environment variable.
 |  | 6. The directories mapped in a network.
CMDSHOW | numeric | Specifies how a Windows application window is to be shown. See the description of the SHOWWINDOW function for a list of the acceptable values for the CMDSHOW parameter. For a non-Windows application, the program-information file (PIF), if any, for the application determines the window state.


WINEXEC Errors

WINEXEC Errors

The error value may be one of the following:

Value | Meaning
0 | System was out of memory, executable file was corrupt, or relocations were invalid.
2 | File was not found.
3 | Path was not found.
5 | Attempt was made to dynamically link to a task, or there was a sharing or network-protection error.
6 | Library required separate data segments for each task.
8 | There was insufficient memory to start the application.
10 | Windows version was incorrect.
11 | Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12 | Application was designed for a different operating system.
13 | Application was designed for MS-DOS 4.0.
14 | Type of executable file was unknown.
15 | Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16 | Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19 | Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20 | Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21 | Application requires Microsoft Windows 32-bit extensions.


WINHELP

System Windows API Function

The WINHELP function starts Windows Help (WINHELP.EXE) and passes optional data indicating the nature of the help requested by the application. The application specifies the name and, where required, the path of the help file that the Help application is to display.

Calling Sequence

CALL WINHELP USING WIN-RETURN WND-H HELPFILE COMMAND DWDATA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window requesting Help. The WINHELP function uses this handle to keep track of which applications have requested Help.
HELPFILE | alphanumeric | A string containing the path, if necessary, and the name of the help file that the Help application is to display. The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file.
COMMAND | numeric | Specifies the type of help requested. For a list of possible values and how they affect the value to place in the DWDATA parameter, see the Comments section.
DWDATA | PIC X | Specifies additional data. The value used depends on the value of the COMMAND parameter. For a list of possible values, see the Comments section.


Winhelp Comments

WINHELP Comments

Before closing the window that requested the help, the application must call WINHELP with COMMAND set to HELP-QUIT. Until all applications have done this, Windows Help does not terminate.

The following table shows the possible values for the COMMAND parameter and the corresponding formats of the DWDATA parameter:

COMMAND | DWDATA | Action
HELP-CONTEXT | An unsigned long integer containing the context number for the topic. | Displays Help for a particular topic identified by a context number that has been defined in the [MAP] section of the .HPJ file.
HELP-CONTENTS | Ignored; applications should set to 0L. | Displays the Help contents topic as defined by the Contents option in the [OPTIONS] section of the .HPJ file.
HELP-SETCONTENTS | An unsigned long integer containing the context number for the topic the application wants to designate as the Contents topic. | Determines which Contents topic Help should display when a user presses the F1 key.
HELP-CONTEXTPOPUPS | An unsigned long integer containing the context number for a topic. | Displays in a pop-up window a particular Help topic identified by a context number that has been defined in the [MAP] section of the .HPJ file.
HELP-KEY | A long pointer to a string that contains a keyword for the desired topic. | Displays the topic found in the keyword list that matches the keyword passed in the DWDATA parameter if there is one exact match. If there is more than one match, displays the Search dialog box with the topics listed in the Go To list box.
HELP-PARTIALKEY | A long pointer to a string that contains a keyword for the desired topic. | Displays the topic found in the keyword list that matches the keyword passed in the DWDATA parameter if there is one exact match. If there is more than one match, displays the Search dialog box with the topics found listed in the Go To list box. If there is no match, displays the Search dialog box. If you just want to bring up the Search dialog box without passing a keyword (the third result), you should use a long pointer to an empty string.
HELP-MULTIKEY | A long pointer to the MULTIKEYHELP structure, as defined in WINDOWS.H. This structure specifies the table footnote character and the keyword. | Displays the Help topic identified by a keyword in an alternate key word table.
HELP-COMMAND | A long pointer to a string that contains a Help macro to be executed. | Executes a Help macro.
HELP-SETWINPOS | A long pointer to the HELPWININFO structure, as defined in WINDOWS.H. This structure specifies the size and position of the primary Help window or a secondary window to be displayed. | Displays the Help window if it is minimized or in memory, and positions it according to the data passed.
HELP-FORCEFILE | Ignored; applications should set to 0L. | Ensures that WinHelp is displaying the correct Help file. If the correct Help file is currently displayed, there is no action. If the incorrect Help file is displayed, WinHelp opens the correct file.
HELP-HELPONHELP | Ignored; applications should set to 0L. | Displays the Contents topic of the designated Using Help file.
HELP-QUIT | Ignored; applications should set to 0L. | Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application.


Window Functions

The Windows API window functions create, destroy, show, hide, modify, and move windows, and obtain information about the number and position of the windows on the screen.

The following table summarizes the window functions.

Note The detailed explanation of each function discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Function | Description
CLIENTTOSCREEN | Converts the client coordinates of a given point on the window-to-screen coordinates.
CLOSEWINDOW | Minimizes (but does not destroy) the specified window.
CREATEWINDOW | Creates an overlapped, pop-up, or child window.
CREATEWINDOWEX | Creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CREATEWINDOW function.
DESTROYWINDOW | Destroys the specified window.
ENABLEWINDOW | Enables or disables mouse and keyboard input to a window.
FINDWINDOW | Finds a window based on its class name and title.
FLASHWINDOW | Flashes the given window once.
GETACTIVEWINDOW | Returns the window handle of the active window.
GETCLIENTRECT | Retrieves the coordinates of a window’s client area.
GETFOCUS | Retrieves the handle of the window that currently has the input focus.
GETPARENT | Returns the handle of the specified window’s parent window (if any).
GETTOPWINDOW | Returns the handle of the top-level child window that belongs to the given parent window.
GETWINDOW | Returns the handle of a window that has the specified relationship to the given window.
GETWINDOWLONG | Retrieves a long value at the specified offset from the extra window memory associated with the given window.
GETWINDOWRECT | Retrieves the dimensions of the bounding rectangle of a specified window.
GETWINDOWTEXT | Copies text of the given window’s title bar (if it has one) into a field.
GETWINDOWTEXTLENGTH | Retrieves the length, in bytes, of the text in the specified window’s title bar.
GETWINDOWWORD | Retrieves a word value at the specified offset from the extra window memory associated with the given window.
ISCHILD | Determines whether a given window is a child or other direct descendant of a given parent window.
ISICONIC | Determines whether the given window is minimized (iconic).
ISWINDOW | Determines whether the given window handle is valid.
ISWINDOWENABLED | Determines whether the specified window is enabled for mouse and keyboard input.
ISWINDOWVISIBLE | Determines whether the given window is visible.
ISZOOMED | Determines whether the given window is maximized.
LOCKWINDOWUPDATE | Disables or re-enables drawing in the given window.
MOVEWINDOW | Changes the position and size of a window.
OPENICON | Activates and displays a minimized window.
POSTMESSAGE | Sends the specified message to the given window or windows, and returns without waiting for it to be processed.
SCREENTOCLIENT | Converts the screen coordinates of a given point on the screen-to-client coordinates.
SENDMESSAGE | Sends the specified message to the given window or windows.
SETACTIVEWINDOW | Makes the specified top-level window the active window. Compare this function to SETFOREGROUNDWINDOW.
SETFOCUS | Assigns the input focus to the specified window.
SETFOREGROUNDWINDOW | Makes the specified top-level window the foreground window. Compare this function to SETACTIVEWINDOW.
SETPARENT | Changes the parent window of the given child window.
SETWINDOWLONG | Sets a long value at the specified offset in the extra window memory of the given window.
SETWINDOWTEXT | Sets the given window’s title to the specified text.
SETWINDOWWORD | Sets a word value at the specified offset in the extra window memory associated with the given window.
SHOWOWNEDPOPUPS | Shows or hides all pop-up windows owned by the given window.
SHOWWINDOW | Sets the visibility state of the given window.
UPDATEWINDOW | Updates the client area of the given window by sending a WM-PAINT message to the window if the update region for the window is not empty.


CLIENTTOSCREEN

Window Windows API Function

The CLIENTTOSCREEN function converts the client coordinates of a given point on the screen to screen coordinates. The CLIENTTOSCREEN function replaces the coordinates in the POINT structure with the screen coordinates. The screen coordinates are relative to the upper-left corner of the screen.

Calling Sequence

CALL CLIENTTOSCREEN USING WND-H POINT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose client area is used for the conversion.
POINT | windows.cpy | A POINT structure that contains the client coordinates to be converted.


CLOSEWINDOW

Window Windows API Function

The CLOSEWINDOW function minimizes (but does not destroy) the given window. To destroy a window, an application must use the DESTROYWINDOW function.

This function has no effect if the WND-H parameter identifies a pop-up or child window.

Calling Sequence

CALL CLOSEWINDOW USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be minimized.


CREATEWINDOW

Window Windows API Function

The CREATEWINDOW function creates an overlapped, pop-up, or child window. The CREATEWINDOW function specifies the window class, window title, window style, and the initial position and size of the window. The CREATEWINDOW function also specifies the window’s parent (if any) and menu.

Calling Sequence

CALL CREATEWINDOW USING WND-H CLASSNAME WINDOWNAME
WIN-STYLE X Y WIDTH HEIGHT PARENT-H MENU-H.

Parameter

Declaration

Description

WND-H

PIC 9(10) BINARY(8)

The return value is the handle of the new window if the function is successful. Otherwise, it is zero.

CLASS-NAME

alphanumeric

Specifies the window class. The class name can be any name registered with the REGISTERCLASS function or any of the predefined control-class names. (For more information on predefined control classes that may be specified in this parameter, see the discussion in the Comments section.)

WINDOW-NAME

alphanumeric

Contains the window name.

WIN-STYLE

windows.cpy

Specifies the style of window being created. This parameter can be a combination of the control styles and window styles that are described in the Comments and the WIN-STYLE parameter sections.

X

numeric

Specifies the initial x-position of the window. For an overlapped or pop-up window, the X parameter is the initial x-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, X is the x-coordinate of the upper-left corner of the window in the client area of its parent window.

If this value is WIN-CW-USEDEFAULT, Windows selects the default position for the window’s upper-left corner and ignores the Y parameter. WIN-CW-USEDEFAULT is valid only for overlapped windows. If WIN-CW-USEDEFAULT is specified for a non-overlapped window, the X and Y parameters are set to zero.

Y

numeric

Specifies the initial y-position of the window. For an overlapped window, the Y parameter is the initial y-coordinate of the window’s upper-left corner. For a pop-up window, Y is the y-coordinate, in screen coordinates, of the upper-left corner of the pop-up window. For list box controls, Y is the y-coordinate of the upper-left corner of the control’s client area. For a child window, Y is the y-coordinate of the upper-left corner of the child window. All of these coordinates are for the window, not the window’s client area.

If an overlapped window is created with the WS-VISIBLE style and the X parameter set to WIN-CW-USEDEFAULT, Windows ignores the Y parameter.

WIDTH

numeric

Specifies the width, in device units, of the windows. For overlapped windows, the WIDTH parameter is either the window’s width ( in screen coordinates) or WIN-CW-USEDEFAULT. If WIDTH is WIN-CW-USEDEFAULT, Windows selects a default width and height for the window (the default width extends from the initial x-position to the right edge of the screen, and the default height extends from the initial y-position to the top of the icon area). WIN-CW-USEDEFAULT is valid only for overlapped windows. If WIN-CW-USEDEFAULT is specified in WIDTH for a non-overlapped window, WIDTH and HEIGHT are set to zero.

HEIGHT

numeric

Specifies the height, in device units, of the window. For overlapped windows, the HEIGHT parameter is the window’s height in screen coordinates. If the WIDTH parameter is WIN-CW-USEDEFAULT, Windows ignores HEIGHT.

PARENT-H

PIC 9(10) BINARY(8)

The handle of the parent or owner window of the window being created. A valid window handle must be supplied when creating a child window or an owned window. An owned window is an overlapped window that is destroyed when its owner window is destroyed, hidden when its owner is minimized, and that is always displayed on top of its owner window. For pop-up windows, a handle can be supplied but is not required. If the window does not have a parent window or is not owned by another window, the PARENT-H parameter must be set to zero.

MENU-H

PIC 9(10) BINARY(8)

The handle of a menu or a child window. This parameter’s meaning depends on the window style. For overlapped or pop-up windows, the MENU-H parameter identifies the menu to be used with the window. It can be zero, if the class menu is to be used. For child windows, MENU-H identifies the child window and is a value that is used by a window control to notify its parent of events (such as the EN-HSCROLL message). The child window identifier is determined by the application and should be unique for all child windows with the same parent window.


Create Window Comments

CREATEWINDOW Comments

For overlapped, pop-up, and child windows, the CREATEWINDOW function sends a WM-CREATE message to the window. If the WS-VISIBLE style is specified, CREATEWINDOW sends the window all the messages required to activate and show the window.

If the window style specifies a title bar, the window title contained in the WINDOW-NAME parameter is displayed in the title bar. When using CREATEWINDOW to create controls such as buttons, check boxes, and edit box controls, use the WINDOW-NAME parameter to specify the text of the control.

The following lists the predefined control classes that an application can specify in the CLASS-NAME parameter.

Class

Meaning

BUTTON

Designates a small rectangular child window that represents a button the user can turn on or off by clicking. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.

COMBOBOX

Designates a control consisting of a list box and a selection field similar to an edit box control. The list box may be displayed at all times or may be dropped down when the user selects a pop-up list box next to the selection field.

Depending on the style of the combo box, the user can or cannot edit the contents of the selection field. If the list box is visible, typing characters into the selection box will cause the first box entry that matches the characters typed to be highlighted. Conversely, selecting an item in the list box displays the selected text in the selection field.

EDIT

Designates a rectangular child window in which the user can type text from the keyboard. The user selects the control, and gives it the input focus by clicking it or moving to it by pressing the TAB key. The user can type text when the control displays a flashing caret. The mouse can be used to move the cursor and select characters to be replaced, or to position the cursor for inserting characters. The BACKSPACE key can be used to delete characters.

Edit box controls use the variable-pitch System font and display characters from the ANSI character set. An application can also send the WM-SETFONT message to the edit box control to change the default font.

Edit box controls expand tab characters into as many space characters as are required to move the cursor to the next tab stop. Tab stops are assumed to be at every eighth character position.

LISTBOX

Designates a list of character strings. This control is used whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by pointing to it and clicking. When a string is selected, it is highlighted and a notification message is passed to the parent window. A vertical or horizontal scroll bar can be used with a list box control to scroll lists that are too long for the control window. The list box automatically hides or shows the scroll bar as needed.

MDICLIENT

Designates an MDI client window. The MDI client window receives messages that control the MDI application’s child windows. The recommended style bits are WS-CLIPCHILDREN and WS-CHILD. To create a scrollable MDI client window that allows the user to scroll MDI child windows into view, an application can also use the WS-HSCROLL and WS-VSCROLL styles.

SCROLLBAR

Designates a rectangle that contains a scroll box (also called a “thumb”) and has direction arrows at both ends. The scroll bar sends a notification message to the parent window whenever the user clicks the control. The parent window is responsible for updating the position, if necessary. Scroll bar controls have the same appearance and function as scroll bars used in ordinary windows. Unlike scroll bars, however, scroll bar controls can be positioned anywhere in a window and used whenever needed to provide scrolling input for a window.

The scroll bar class also includes size box controls (Maximize and Minimize buttons). These controls are small rectangles that the user can click to change the size of the windows.

STATIC

Designates a simple text field, box, or rectangle that can be used to label, box, or separate other controls. Static controls take no input and provide no output.


WIN-STYLE Parameter

WIN-STYLE Parameter

The following lists the window styles that an application can specify in the WIN-STYLE parameter.

See the following related topics:

· CREATEWINDOW function

· CREATEWINDOWEX function

· WOWCREATEWINDOW function

 | Style | Meaning
MDIS-ALLCHILDSTYLES |  | Creates an MDI client window that can have any combination of window styles. When this style is not specified, an MDI child window has the WS-MINIMIZE, WS-MAXIMIZE, WS-SCROLL, and WS-VSCROLL styles as default settings.
WS-BORDER |  | Creates a window that has a border.
WS-CAPTION |  | Creates a window that has a title bar (includes the WS-BORDER style). This style cannot be used with the WS-DLGFRAME style.
WS-CHILD |  | Creates a child window. This style cannot be used with the WS-POPUP style.
WS-CHILDWINDOW |  | Functions the same as the WS-CHILD style.
WS-CLIPCHILDREN |  | Excludes the area occupied by child windows when drawing within the parent window. This style is used when creating the parent window.
WS-CLIPSIBLINGS |  | Clips child windows relative to each other; that is, when a particular child window receives a WM-PAINT message, the WS-CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. (If WS-CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.) Use only with the WS-CHILD style.
WS-DISABLED |  | Creates a window that is initially disabled.
WS-DLGFRAME |  | Creates a window with a double border. A window with this style cannot have a title bar.
WS-GROUP |  | Specifies the first control of a group of controls in which the user can move from one control to the next by using the arrow direction keys. All controls defined with the WS-GROUP style after the first control belong to the same group. The next control with the WS-GROUP style ends the style group and starts the next group (that is, one group ends where the next begins). Only dialog boxes can use this style.
WS-HSCROLL |  | Creates a window that has a horizontal scroll bar.
WS-MAXIMIZE |  | Creates a window that is initially maximized.
WS-MAXIMIZEBOX |  | Creates a window that has a Maximize button. The WS-SYSMENU style must also be specified.
WS-MINIMIZE |  | Creates a window that is initially minimized. Use only with the WS-OVERLAPPED style.
WS-MINIMIZEBOX |  | Creates a window that has a Minimize button.
WS-OVERLAPPED |  | Creates an overlapped window. An overlapped window has a title and a border.
WS-OVERLAPPEDWINDOW |  | Creates an overlapped window having the WS-OVERLAPPED, WS-CAPTION, WS-SYSMENU, WS-THICKFRAME, WS-MINIMIZEBOX, and WS-MAXIMIZEBOX styles.
WS-POPUP |  | Creates a pop-up window. This style cannot be used with the WS-CHILD style.
WS-POPUPWINDOW |  | Creates a pop-up window that has the WS-BORDER, WS-POPUP, and WS-SYSMENU styles. The WS-CAPTION style must be combined with the WS-POPUPWINDOW style to make the System (or Control) menu visible.
WS-SYSMENU |  | Creates a window that has a System-menu (Control-menu) box in its title bar. This style can be used only for windows with title bars. The WS-CAPTION style must also be specified.
WS-TABSTOP |  | Specifies one of any number of controls through which the user can move by using the Tab key. Pressing the TAB key moves the user to the next control specified by the WS-TABSTOP style. Only dialog boxes use this style.
WS-THICKFRAME |  | Creates a window with a thick frame that can be used to size the window.
WS-VISIBLE |  | Creates a window that is initially visible. This style applies to overlapped, child, and pop-up windows. For overlapped windows, the Y parameter is used as a SHOWWINDOW function parameter.
WS-VSCROLL |  | Creates a window that has a vertical scroll bar.

The following styles may also be specified in the WIN-STYLE parameter when a predefined control is being created:

· Button styles

· Combo box styles

· Edit box control styles

· List box styles

· Scroll bar styles

· Static control styles

The following lists the dialog box styles an application can specify in the WIN-STYLE parameter.

Style | Meaning
DS-MODALFRAME | Creates a dialog box with a modal dialog box frame that can be combined with a title bar and System (or Control) menu by specifying the WS-CAPTION and WS-SYSMENU styles.
DS-NOIDLEMSG | Suppresses WM-ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS-SYSMODAL | Creates a system-modal dialog box.


CREATEWINDOWEX

Window Windows API Function

The CREATEWINDOWEX function creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CREATEWINDOW function.

The CREATEWINDOWEX function sends a WM-CREATE message to the window being created.

Calling Sequence

CALL CREATEWINDOWEX USING WND-H WIN-EX-STYLE CLASS-NAME
WINDOW-NAME WIN-STYLE X Y WIDTH HEIGHT PARENT-H MENU-H.

 | Parameter | Declaration | Description
WND-H |  | PIC 9(10) BINARY(8) | The return value identifies the new window if the function is successful. Otherwise, it is zero.
 | WIN-EX-STYLE | windows.cpy | Specifies the extended style of the window. This parameter can be one of the following values:
 |  | Style | Meaning
 |  | WS-EX-ACCEPTFILES | Specifies that a window created with this style accepts drag-drop files.
 |  | WS-EX-DLGMODALFRAME | Designates a window with a double border that may (optionally) be created with a title bar by specifying the WS-CAPTION style flag in the WIN-STYLE parameter.
 |  | WS-EX-NOPARENTNOTIFY | Specifies that a child window created by using this style will not send the WM-PARENTNOTIFY message to its parent window when the child window is created or destroyed.
 |  | WS-TOPMOST | Specifies that a window created with this style should be placed above all non-topmost windows and stay above them even when the window is deactivated.
 |  | WS-EX-TRANSPARENT | Specifies that a window created with this style is to be transparent. That is, the window does not obscure any windows that are beneath it. A window created with this style receives WM-PAINT messages only after all sibling windows beneath it have been updated.
 | CLASS-NAME | alphanumeric | Contains the name of the window class.
 | WINDOW-NAME | alphanumeric | Contains the name of the window.
 | WIN-STYLE | windows.cpy | Specifies the style of the window. For a list of the window styles that can be specified in this parameter, see the WIN-STYLE parameter section in the discussion of the CREATEWINDOW function.
 | X | numeric | Specifies the initial left-side position of the window.
 | Y | numeric | Specifies the initial top position of the window.
 | WIDTH | numeric | Specifies the width, in device units, of the window.
 | HEIGHT | numeric | Specifies the height, in device units, of the window.
 | PARENT-H | PIC 9(10) BINARY(8) | The handle of the parent or owner window of the window to be created.
 | MENU-H | PIC 9(10) BINARY(8) | The handle of a menu or a child window. The meaning depends on the window style.


DESTROYWINDOW

Window Windows API Function

The DESTROYWINDOW function destroys the specified window. The function sends appropriate messages to the window to deactivate it and remove the input focus. It also destroys the window’s menu, flushes the application queue, destroys outstanding timers, removes clipboard ownership, and breaks the clipboard-viewer chain (if the window is at the top of the viewer-chain). It sends a WM-DESTROY message to the window.

If the given window is the parent of any windows, DESTROYWINDOW automatically destroys these child windows when it destroys the parent window. The function destroys child windows first and then the window itself.

Applications should always call the DESTROYWINDOW function to destroy their top-level windows before terminating.

If the window being destroyed is a child window and does not have the WS-EX-NOPARENTNOTIFY style set, a WM-PAINT message is sent to the parent.

Calling Sequence

CALL DESTROYWINDOW USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be destroyed.


ENABLEWINDOW

Window Windows API Function

The ENABLEWINDOW function enables or disables mouse and keyboard input to the given window or control. When input is disabled, the window ignores input such as mouse clicks and key presses. When input is enabled, the window processes all input.

If the enabled state of the window is changing, a WM-ENABLE message is sent before this function returns. If a window is already disabled, all its child windows are implicitly disabled, although they are not sent a WM-ENABLE message.

A window must be enabled before it can be activated. For example, if an application is displaying a pop-up window and has disabled its main window, the application must enable the main window before destroying the pop-up window. Otherwise, another window will receive the input focus and be activated. If a child window is disabled, it is ignored when Windows tries to determine which window should receive mouse messages.

By default, a window is enabled when it is created. An application can specify the WS-DISABLED style in the WIN-STYLE parameter of the CREATEWINDOW or CREATEWINDOWEX function to create a window that is initially disabled. After a window has been created, an application can use the ENABLEWINDOW function to enable or disable the window.

An application can use this function to enable or disable a control in a window. A disabled control cannot receive the input focus, nor can a user access it.

Calling Sequence

CALL ENABLEWINDOW USING WIN-RETURN WND-H STATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window was previously disabled. Otherwise, the return value is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be enabled or disabled.
STATE | windows.cpy | Specifies whether to enable or disable the window. If the value of this parameter is WIN-TRUE, the window is enabled. If the value of this parameter is WIN-FALSE, the window is disabled.


FINDWINDOW

Window Windows API Function

The FINDWINDOW function retrieves the handle of the window whose class name and window name match the specified strings. This function does not search child windows.

Calling Sequence

CALL FINDWINDOW USING WND-H CLASSNAME WINDOW.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that has the specified class name and window name if the function is successful. Otherwise, it is zero.
CLASSNAME | alphanumeric | A string that contains the window’s class name. If the value of this parameter is blank, all class names match.
WINDOW | alphanumeric | A string that specifies the window name (the window’s title). If the value of this parameter is blank, all window names match.


FLASHWINDOW

Window Windows API Function

The FLASHWINDOW function flashes the given window once. Flashing a window means changing the appearance of its title bar as if the window were changing from inactive to active status or vice versa. (An inactive title bar changes to an active bar or an active title bar changes to an inactive title bar.)

Typically, a window is flashed to inform the user that the window requires attention but that it does not currently have the input focus.

The FLASHWINDOW function flashes the window only once; for successive flashing, the application should create a system timer.

The value of the CHANGE-STATE parameter should be WIN-FALSE only when the window is receiving the input focus and will no longer be flashing; it should be WIN-TRUE on successive calls while waiting to get the input focus.

This function always returns nonzero for minimized windows. If the window is minimized, FLASHWINDOW simply flashes the window’s icon; the CHANGE-STATE parameter is ignored for minimized windows.

Calling Sequence

CALL FLASHWINDOW USING WIN-RETURN WND-H CHANGE-STATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window was active before the call to the FLASHWINDOW function. Otherwise, it is zero
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be flashed. The window can be either open or minimized.
CHANGE-STATE | windows.cpy | Specifies whether to flash the window or return it to its original state. If the value of this parameter is WIN-TRUE, the window is flashed from one state to the other. If the value of this parameter is WIN-FALSE, the window is returned to its original state (either active or inactive).


GETACTIVEWINDOW

Window Windows API Function

The GETACTIVEWINDOW function retrieves the window handle of the active window. The active window is either the top-level window associated with the input focus or the window explicitly made active by the SETACTIVEWINDOW function.

Calling Sequence

CALL GETACTIVEWINDOW USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The return value is the handle of the active window or zero if no window was active at the time of the call.


GETCLIENTRECT

Window Windows API Function

The GETCLIENTRECT function retrieves the client coordinates of a window’s client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window’s client area, the coordinates of the upper-left corner are (0,0).

Calling Sequence

CALL GETCLIENTRECT USING WND-H RECT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose client coordinates are to be retrieved.
RECT | windows.cpy | A RECT structure that receives the client coordinates. The left and top members will be zero. The right and bottom members will contain the width and height of the window.


GETFOCUS

Window Windows API Function

The GETFOCUS function retrieves the handle of the window that currently has the input focus.

Calling Sequence

CALL GETFOCUS USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The return value is the handle of the focus window. If no window has the focus, it is zero.


GETPARENT

Window Windows API Function

The GETPARENT function retrieves the handle of the given window’s parent window (if any).

Calling Sequence

CALL GETPARENT USING PARENT-H WND-H.

Parameter | Declaration | Description
PARENT-H | PIC 9(10) BINARY(8) | The return value is the handle of the parent window if the function is successful. Otherwise, it is zero, indicating an error or no parent window.
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose parent window handle is to be retrieved.


GETTOPWINDOW

Window Windows API Function

The GETTOPWINDOW function retrieves the handle of the top-level child window that belongs to the given parent window. If the parent window has no child windows, this function returns zero.

Calling Sequence

CALL GETTOPWINDOW USING TOP-H WND-H.

Parameter | Declaration | Description
TOP-H | PIC 9(10) BINARY(8) | The return value is the handle of the top-level child window in a parent window’s linked list of child windows if the function is successful. Otherwise, the return value is zero if no child windows exist.
WND-H | PIC 9(10) BINARY(8) | The handle of the parent window. If the value of this parameter is zero, the function returns the first child window of the desktop window.


GETWINDOW

Window Windows API Function

The GETWINDOW function retrieves the handle of a window that has the specified relationship to the given window. The function searches the system’s list of top-level windows, their associated child windows, the child windows of any child windows, and any siblings of the owner or a window.

Calling Sequence

CALL GETWINDOW USING REL-H WND-H RELATION.

Parameter | Declaration | Description
REL-H | PIC 9(10) BINARY(8) | The return value is the handle of the window if the function is successful. Otherwise, it is zero, indicating either the end of the system’s list or an invalid RELATION parameter.
WND-H | PIC 9(10) BINARY(8) | The handle of the original window.
RELATION | numeric | Specifies the relationship between the original window and the returned window. This parameter can be one of the following values:
 | Value | Meaning
 | GWCHILD | The handle of the window’s first child window.
 | GWHWNDFIRST | Returns the first sibling window for a child window; otherwise, it returns the first top-level window in the list.
 | GWHWNDLAST | Returns the last sibling window for a child window; otherwise, it returns the last top-level window in the list.
 | GWHWNDNEXT | Returns the sibling window that follows the given window in the window manager’s list.
 | GWHWNDPREV | Returns the previous sibling window in the window manager’s list.
 | GWOWNER | The handle of the window’s owner.


GETWINDOWLONG

Window Windows API Function

The GETWINDOWLONG function retrieves a long value at the specified offset into the extra window memory of the given window. Extra window memory is reserved by specifying a nonzero value in the CBWINEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

To access any extra four-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first four-byte value in the extra space, 4 for the next four-byte value, and so on.

Calling Sequence

CALL GETWINDOWLONG USING WIN-RETURN WND-H OFFSET.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies information about the given window if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus four (for example, if 12 or more bytes of extra memory was specified, a value of 8 would be an index to the third long integer), or one of the following values:
 | Value | Meaning
 | GWL-EXSTYLE | Extended window style.
 | GWL-STYLE | Window style.
 | GWL-WNDPROC | Long pointer to the windows procedure.
 |  | The following values are also available when the WND-H parameter identifies a dialog box:
 | Value | Meaning
 | DWL-DLGPROC | Specifies the address of the dialog box procedure.
 | DWL-MSGRESULT | Specifies the return value of a message processed in the dialog box procedure.
 | DWL-USER | Specifies extra information that is private to the application, such as handles or pointers.


GETWINDOWRECT

Window Windows API Function

The GETWINDOWRECT function retrieves the dimensions of the bounding rectangle of a given window. The dimensions are given in screen coordinates, relative to the upper-left corner of the display screen, and include the title bar, border, and scroll bars, if present.

Calling Sequence

CALL GETWINDOWRECT USING WND-H RECT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
RECT | windows.cpy | A RECT structure, declared under “RECT GLOBAL” in windows.cpy, that receives the screen coordinates of the upper-left and lower-right corners of the window.


GETWINDOWTEXT

Window Windows API Function

The GETWINDOWTEXT function copies text of the given window’s title bar (if it has one) into a buffer. If the given window is a control, the text within the control is copied.

This function causes a WM-GETTEXT message to be sent to the given window or control.

Calling Sequence

CALL GETWINDOWTEXT USING WIN-RETURN WND-H BUFFER MAX-SIZE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the length, in bytes, of the copied string, if the function is successful. It is zero if the window has no title bar, the title bar is empty, or the WND-H parameter is invalid.
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control containing the title bar or text.
BUFFER | alphanumeric | A buffer that will receive the title bar or text.
MAX-SIZE | numeric | Specifies the maximum number of characters to copy to the buffer. The title bar or text is truncated if it is longer than the number of characters specified in MAX-SIZE. If this value is zero, the size of the buffer will be calculated.


GETWINDOWTEXTLENGTH

Window Windows API Function

The GETWINDOWTEXTLENGTH function retrieves the length, in bytes, of the text in the given window’s title bar. If the window is a control, the length of the text within the control is retrieved.

This function causes the WM-GETTEXTLENGTH message to be sent to the given window or control.

Calling Sequence

CALL GETWINDOWTEXTLENGTH USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the text length, in bytes, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control.


GETWINDOWWORD

Window Windows API Function

The GETWINDOWWORD function retrieves a word value at the specified offset into the extra window memory of the given window. Extra window memory is reserved by specifying a nonzero value in the CBWNDEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

To access any extra two-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first two-byte value in the extra space, 2 for the next two-byte value, and so on.

Calling Sequence

CALL GETWINDOWWORD USING WIN-RETURN WND-H OFFSET.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies information about the given window if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus two (for example, if 10 or more bytes of extra memory was specified, a value of 8 would be an index to the fifth integer), or one of the following values:
 | Value | Meaning
 | GWW-HINSTANCE | Specifies the instance handle of the module that owns the window.
 | GWW-HWNDPARENT | Specifies the handle of the parent window, if any. The SETPARENT function changes the parent window of a child window. An application should not call the SETWINDOWWORD function to change the parent of a child window.
 | GWW-ID | Specifies the identifier of the child window.


ISCHILD

Window Windows API Function

The ISCHILD function tests whether a given window is a child or other direct descendant of a given parent window. A child window is the direct descendant of a given parent window if that parent window is in the chain of parent windows leading from the original pop-up window to the child window.

Calling Sequence

CALL ISCHILD USING WIN-RETURN PARENT-H CHILD-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the child window is a descendant of the parent window. Otherwise, it is zero.
PARENT-H | PIC 9(10) BINARY(8) | The handle of the parent window.
CHILD-H | PIC 9(10) BINARY(8) | The handle of the child window to be tested.


ISICONIC

Window Windows API Function

The ISICONIC function determines whether the given window is minimized (iconic).

Calling Sequence

CALL ISICONIC USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window is minimized. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.


ISWINDOW

Window Windows API Function

The ISWINDOW function determines whether the given window handle is valid.

Calling Sequence

CALL ISWINDOW USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window handle is valid. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of a window.


ISWINDOWENABLED

Window Windows API Function

The ISWINDOWENABLED function determines whether the given window is enabled for mouse and keyboard input. A child window receives input only if it is both enabled and visible.

Calling Sequence

CALL ISWINDOWENABLED USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window is enabled. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.


ISWINDOWVISIBLE

Window Windows API Function

The ISWINDOWVISIBLE function determines the visibility state of the given window.

A window possesses a visibility state indicated by the WS-VISIBLE style bit. When this style bit is set, the window is displayed and subsequent drawing into the window is displayed as long as the window has the style bit set.

Any drawing to a window that has the WS-VISIBLE style will not be displayed if the window is covered by other windows or is clipped by its parent window.

Calling Sequence

CALL ISWINDOWVISIBLE USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the specified window is visible on the screen (has the WS-VISIBLE style bit set). The return value is zero if the window is not visible. Because the return value reflects the value of the window’s WS-VISIBLE flag, it may be nonzero even if the window is totally obscured by other windows.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.


ISZOOMED

Window Windows API Function

The ISZOOMED function determines whether the given window is maximized.

Calling Sequence

CALL ISZOOMED USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window is maximized. Otherwise, it is zero
WND-H | PIC 9(10) BINARY(8) | The handle of the window.


LOCKWINDOWUPDATE

Window Windows API Function

The LOCKWINDOWUPDATE function disables or re-enables drawing in the given window. A locked window cannot be moved. Only one window can be locked at a time.

While window updates are locked, the system keeps track of the bounding rectangle of any drawing operations to device contexts associated with a locked window. When drawing is re-enabled, this bounding rectangle is invalidated in the locked window and its child windows to force an eventual WM-PAINT message to update the screen. If no drawing has occurred while the window updates were locked, no area is invalidated.

The LOCKWINDOWUPDATE function does not make the given window invisible and does not clear the WS-VISIBLE style bit.

Calling Sequence

CALL LOCKWINDOWUPDATE USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. It is zero if a failure occurs or if the LOCKWINDOWUPDATE function has been used to lock another window.
WND-H | PIC 9(10) BINARY(8) | The handle of the window in which drawing will be disabled. If the value of this parameter is zero, drawing in the locked window is enabled.


MOVEWINDOW

Window Windows API Function

The MOVEWINDOW function changes the position and dimensions of a window. For top-level windows, the position and dimensions are relative to the upper-left corner of the screen. For child windows, they are relative to the upper-left corner of the parent window’s client area.

Note Using MOVEWINDOW to move or resize a form sets the absolute size of the form, including the borders and title bar. Contrast this behavior with that of WOWSETPROP, which can be used to set the width and height of the form’s client area. Providing identical values to MOVEWINDOW and WOWSETPROP for width and height will result in forms of different sizes.

Calling Sequence

CALL MOVEWINDOW USING WIN-RETURN WND-H LEFT TOP WIDTH HEIGHT REPAINT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be changed.
LEFT | numeric | Specifies the new position of the left side of the window.
TOP | numeric | Specifies the new position of the top of the window.
WIDTH | numeric | Specifies the new width of the window.
HEIGHT | numeric | Specifies the new height of the window.
REPAINT | windows.cpy | Specifies whether the window is to be repainted. If the value of this parameter is WIN-TRUE, the window receives a WM-PAINT message, as usual. If the value of this parameter is WIN-FALSE, no repainting of any kind occurs. This applies to the client area, the non-client area (including the title and scroll bars), and any part of the parent window uncovered as a result of the moved window. When the value of this parameter is WIN-FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that must be redrawn.


OPENICON

Window Windows API Function

The OPENICON function activates and displays a minimized window. Windows restores the window to its original size and position.

Using OPENICON is the same as specifying the SW-SHOWNORMAL flag in a call to the SHOWWINDOW function.

Calling Sequence

CALL OPENICON USING WIN-RETURN WND-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.


POSTMESSAGE

Window Windows API Function

The POSTMESSAGE function posts (places) a message in a window’s message queue and then returns without waiting for the corresponding window to process the message. Messages in a message queue are retrieved by calls to the WOWGETMESSAGE function.

The POSTMESSAGE function fails if the message queue for the receiving application is full. This is especially likely if an application posts several messages without allowing the receiving task to run. The WOWGETMESSAGE and WOWPEEKMESSAGE functions yield control to other applications.

CAUTION An application should never use the POSTMESSAGE function to post a message to a control.

Calling Sequence

CALL POSTMESSAGE USING WIN-RETURN WND-H MSG-ID WPARAM LPARAM.

Parameter | Declaration | Description
WIN-RETURN | windows.cpy | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be posted. If the value of this parameter is HWND-BROADCAST, the message will be posted to all top-level windows, including disabled or invisible unowned windows.
MSG-ID | numeric | Specifies the message to be posted. Possible values are declared as 78-level descriptions in windows.cpy.
WPARAM | depends on MSG-ID | Specifies 16 bits of additional message-dependent information.
LPARAM | depends on MSG-ID | Specifies 32 bits of additional message-dependent information.


SCREENTOCLIENT

Window Windows API Function

The SCREENTOCLIENT function converts the screen coordinates of a given point on the screen to client coordinates. The SCREENTOCLIENT function replaces the screen coordinates in the POINT structure with client coordinate. The new coordinates are relative to the upper-left corner of the given window’s client area.

Calling Sequence

CALL SCREENTOCLIENT USING WND-H POINT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window whose client area is to be used for the conversion.
POINT | windows.cpy | A POINT structure, declared under “POINT GLOBAL” in windows.cpy, which contains the screen coordinates to be converted.


SENDMESSAGE

Window Windows API Function

The SENDMESSAGE function sends the specified message to the given window or windows. The function calls the window procedure for the window and does not return until that window procedure has processed the message

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H MSG-ID WPARAM LPARAM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the result of the message processing and depends on the message sent if the function is successful. Otherwise, it is zero..
WND-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent. If the value of this parameter is HWND-BROADCAST, the message will be sent to all top-level windows, including disabled or invisible unowned windows.
MSG-ID | numeric | Specifies the message to be sent. Possible values are declared as 78-level descriptions in windows.cpy.
WPARAM | depends on MSG-ID | Specifies 16 bits of additional message-dependent information.
LPARAM | depends on MSG-ID | Specifies 32 bits of additional message-dependent information.


SETACTIVEWINDOW

Window Windows API Function

The SETACTIVEWINDOW function makes the specified top-level window the active window. The SETACTIVEWINDOW function activates a window, but not if the application is in the background. The window will be brought into the foreground (that is, the top of the z-order) if the application is in the foreground when it sets the activation.

The SETACTIVEWINDOW function should be used with care, since it allows an application to arbitrarily take over the active window and input focus. Normally, Windows takes care of all activation.

CAUTION The SETACTIVEWINDOW function should not be confused with SETFOREGROUNDWINDOW, even though both functions bring the active window to the foreground. The SETFOREGROUNDWINDOW function activates a window and forces it into the foreground. An application should call SETFOREGROUNDWINDOW only if it needs to display critical errors or information that needs the user's immediate attention.

Calling Sequence

CALL SETACTIVEWINDOW USING LASTWND-H WND-H.

Parameter | Declaration | Description
LASTWND-H | PIC 9(10) BINARY(8) | The return value is the handle of the window that was previously active, if the function is successful.
WND-H | PIC 9(10) BINARY(8) | The handle of the top-level window to be activated.


SETFOCUS

Window Windows API Function

The SETFOCUS function sets the input focus to the given window. All subsequent keyboard input is directed to this window. The window, if any, which previously had the input focus loses it.

The SETFOCUS function sends a WM-KILLFOCUS message to the window that loses the input focus and a WM-SETFOCUS message to the window that receives the input focus. It also activates either the window that receives the focus or the parent of the window that receives the focus.

If a window is active but does not have the focus (that is, no window has the focus), any key pressed will produce the WM-SYSCHAR, WM-SYSKEYDOWN, or WM-SYSKEYUP message. If the VK-MENU key is also pressed, the LPARAM parameter of the message will have bit 30 set. Otherwise, the messages that are produced do not have this bit set.

This function is equivalent to the WOWSETFOCUS function.

Calling Sequence

CALL SETFOCUS USING PREV-H WND-H.

Parameter | Declaration | Description
PREV-H | PIC 9(10) BINARY(8) | The return value is the handle of the window that previously had the input focus, if the function is successful. It is zero if there is no such window or if the specified handle is invalid.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to receive the keyboard input. If the value of this parameter is zero, keystrokes are ignored.


SETFOREGROUNDWINDOW

Window Windows API Function

The SETFOREGROUNDWINDOW function makes the specified top-level window the foreground window and activates the window. The foreground window is the window at the top of the z-order (or stacking order). It is the window that the user is working with. Compare this function with SETACTIVEWINDOW.

CAUTION An application should call SETFOREGROUNDWINDOW only if it needs to display critical errors or information that needs the user's immediate attention.

Calling Sequence

CALL SETFOREGROUNDWINDOW USING WIN-RETURN WIN-H.

Parameter | Declaration |  | Description
WIN-RETURN |  | numeric |  | If the window was brought to the foreground, the return value is nonzero. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) |  | The handle of the window that should be activated and brought to the foreground.


SETPARENT

Window Windows API Function

The SETPARENT function changes the parent window of the given child window. If the window identified by the CHILD-H parameter is visible, Windows performs the appropriate redrawing and repainting.

Calling Sequence

CALL SETPARENT USING PREV-H CHILD-H NEWPARENT-H.

Parameter | Declaration | Description
PREV-H | PIC 9(10) BINARY(8) | The return value is the handle of the previous parent window, if the function is successful.
CHILD-H | PIC 9(10) BINARY(8) | The handle of the child window.
NEWPARENT-H | PIC 9(10) BINARY(8) | The handle of the new parent window.


SETWINDOWLONG

Window Windows API Function

The SETWINDOWLONG function places a long value at the specified offset into the extra window memory of the given window. Extra window memory is reserved by specifying a nonzero value in the CBWNDEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

An application should not use this function to set the WS-DISABLE style for a window. Instead, the application should use the ENABLEWINDOW function.

To access any extra four-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first four-byte value in the extra space, 4 for the next four-byte value, and so on.

Calling Sequence

CALL SETWINDOWLONG USING WIN-RETURN WND-H OFFSET VAL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the previous value of the specified long integer, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the value to change. Valid values are in the range zero through the number of bytes of extra window memory, minus four (for example, if 12 or more bytes of extra memory were specified, a value of 8 would be an index to the third long integer), or one of the following values:
 | Value | Meaning
 | GWL-EXSTYLE | Extended window style.
 | OFFSET | Window style.
VAL | numeric | Specifies the long value to place in the window’s reserved memory.


SETWINDOWTEXT

Window Windows API Function

The SETWINDOWTEXT function sets the given window’s title to the specified text.

This function causes a WM-SETTEXT message to be sent to the given window or control.

If the window specified by the WND-H parameter is a control, the text within the control is set. If the specified window is a list box control created with the WS-CAPTION style in the WIN-STYLE parameter, however, SETWINDOWTEXT will set the caption for the control, not for the list box entries.

Calling Sequence

CALL SETWINDOWTEXT USING WND-H TEXT.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control whose text is to be set.
TEXT | alphanumeric | A string to be used as the new title or control text.


SETWINDOWWORD

Window Windows API Function

The SETWINDOWWORD function places a word value at the specified offset into the extra window memory of the given window. Extra window memory is reserved by specifying a nonzero value in the CBWNDEXTRA member of the WNDCLASS structure used with the REGISTERCLASS function.

To access any extra two-byte values allocated when the window-class structure was created, use a positive byte offset as the index specified by the OFFSET parameter, starting at 0 for the first two-byte value in the extra space, 2 for the next two-byte value, and so on.

Note An application should call the SETPARENT function, not the SETWINDOWWORD function, to change the parent of a child window.

Calling Sequence

CALL SETWINDOWWORD USING WIN-RETURN WND-H OFFSET VAL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the previous value of the specified word, if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
OFFSET | numeric | Specifies the zero-based byte offset of the value to change. Valid values are in the range zero through the number of bytes of extra window memory, minus two (for example, if 10 or more bytes of extra memory were specified, a value of 8 would be an index to the fifth integer), or one of the following values:
 | Value | Meaning
 | GWW-HINSTANCE | Specifies the instance handle of the module that owns the window.
 | GWW-ID | Specifies the identifier of the child window.
VAL | numeric | Specifies the word value to be placed in the window’s reserved memory.


SHOWOWNEDPOPUPS

Window Windows API Function

The SHOWOWNEDPOPUPS function shows or hides all pop-up windows owned by the given window.

Calling Sequence

CALL SHOWOWNEDPOPUPS USING WND-H SHOW.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window that owns the pop-up windows to be shown or hidden.
SHOW | numeric | Specifies whether pop-up windows are to be shown or hidden. If the value of this parameter is WIN-TRUE, all hidden pop-up windows are shown. If the value of this parameter is WIN-FALSE, all visible pop-up windows are hidden.


SHOWWINDOW

Window Windows API Function

The SHOWWINDOW function sets the given window’s visibility state.

Calling Sequence

CALL SHOWWINDOW USING WIN-RETURN WND-H SHOW.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the window was previously visible. It is zero if the window was previously hidden.
WND-H | PIC 9(10) BINARY(8) | The handle of the window.
SHOW | numeric | Specifies how the window is to be shown. This parameter can be one of the following values:
 | Value | Meaning
 | SW-HIDE | Hides the window and passes activation to another window.
 | SW-MINIMIZE | Minimizes the specified window and activates the top-level window in the system’s list.
 | SW-RESTORE | Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW-SHOWNORMAL).
 | SW-SHOW | Activates a window and displays it in its current size and position.
 | SW-SHOWMAXIMIZED | Activates a window and displays it as a maximized window.
 | SW-SHOWMINIMIZED | Activates a window and displays it as an icon.
 | SW-SHOWMINNOACTIVE | Displays a window as an icon. The window that is currently active remains active.
 | SW-SHOWNA | Displays a window in its current state. The window that is currently active remains active.
 | SW-SHOWNOACTIVATE | Displays a window in its most recent size and position. The window that is currently active remains active.
 | SW-SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW-RESTORE).


UPDATEWINDOW

Window Windows API Function

The UPDATEWINDOW function updates the client area of the given window by sending a WM-PAINT message to the window if the update region for the window is not empty. The function sends a WM-PAINT message directly to the window procedure of the given window, bypassing the application queue. If the update region is empty, no message is sent.

Calling Sequence

CALL UPDATEWINDOW USING WND-H.

Parameter | Declaration | Description
WND-H | PIC 9(10) BINARY(8) | The handle of the window to be updated.


Undocumented Function

This function has not been documented at the time of the general release. Contact Liant Customer Support for more information.


Messages

Using Messages in WOW Extensions

Categories of Messages Used in WOW Extensions

Object-Manipulation Messages

Event-Triggering Messages

Automatically-Processed Messages

Information-Only Messages


Using Messages in WOW Extensions

See Also

This section describes the messages that WOW Extensions uses to communicate with the Windows operating system. Messages are used to communicate between objects and application code. (Objects include each window, or form, as it is called in WOW Extensions, each control, and so forth.) Objects send messages to application code to notify it of actions as they occur. Application code sends messages to objects to manipulate them.

One of the challenges of traditional programming in the Windows environment is handling the messages sent by the Windows operating system to applications. The Windows operating system uses messages extensively. For example, creating a form with a few controls on it will generate dozens of messages. The large number of messages generated by Windows and to which it will respond are key to the flexibility of the Windows operating system. Many of the Windows API functions are shorthand methods of sending appropriate messages and ultimately result in a message being sent to implement their functionality.

WOW Extensions provides code templates, also called shortcuts, for frequently-used messages so that it is easier to understand what the parameters are for a particular message. The available shortcuts are listed in the Code Templates tree on the WOW Designer window.

For more information on using messages in WOW Extensions, click one of the following topics:

· How messages are routed with WOW Extensions

· How messages are implemented

· How messages are received

· How messages are interpreted

· Classes of messages


How Messages are Routed with WOW Extensions

While it does not affect your application programming, it may be useful to understand the way messages are handled within WOW Extensions. When an object (that is, a form or control) is created, an address is specified for a “callback” function for the object. This is the address of code that will interpret and respond to the messages. The Windows operating system will call this code when a message is sent to the object. In C-language programming for Windows, this is referred to as the “window procedure.”

In many COBOL runtime environments, Windows cannot directly call COBOL code. Instead, the window procedure for all WOW Extensions forms or controls is a function within wowrt.dll (the WOW Extensions runtime module). This window procedure is called by Windows whenever a message is sent to a WOW Extensions form or control. The WOW Extensions window procedure stores all these messages in its own message queue. When the WOWGETMESSAGE function executes, it retrieves an entry from the WOW Extensions message queue. For more information on how messages are received, click here.


How Messages are Implemented

A window message is a set of values that Windows sends to a window procedure to provide input to the window or request the window to carry out some actions. The Windows operating system includes a wide variety of messages that it or applications can send to a window procedure. Most messages are sent to a window as a result of a given function being executed or as a result of input from the user.

What is in a Windows message? Every Windows message contains the handle of the window for which the message is intended and the ID number of the message. One or two additional parameters may also be included; their meanings depend on the type of message being sent. Many messages return a value to indicate the result of the message being processed.

The following example illustrates the syntax for sending a message:

CALL SENDMESSAGE USING WIN-RETURN BTN-H BM-SETCHECK 1.

The first parameter, WIN-RETURN, receives the return value from the message, if there is one. The second parameter, BTN-H, specifies the handle that identifies the window to which the message is being sent. The third parameter, BM-SETCHECK, indicates the type of message (ID). In the case of this example, the fourth parameter, 1, is a numeric identifier that indicates whether or not a button is checked.


How Messages are Received

Applications use the WOWGETMESSAGE function within a main message loop to retrieve a message from the message queue. Then, WOW Extensions executes the event-handling code associated with the message, if any. The following example illustrates a WOWGETMESSAGE call:

CALL WOWGETMESSAGE USING WIN-RETURN WIN-MSG-WS AX-EVENT-WS.

WIN-RETURN is included for consistency; however, in this example it is not used. WIN-MSG-WS returns the Windows message. AX-EVENT-WS returns additional information for ActiveX control events.


How Messages are Interpreted

See Also

Interpreting the large number of messages generated by Windows has traditionally been one of the challenges in Windows programming. To eliminate this difficulty, WOW Extensions automatically generates the message interpretation code your application needs. To take advantage of this capability, you enter event-handling code for the objects (the forms, controls, and so forth) and events in the Event-Handling Code window (described in the Designer online Help file) when you design your form.

Although you could manually write the code to interpret these messages, this is an advanced technique that should be performed only after you have substantial experience in Windows programming. If, however, you wish to create your own message code and message-handling methods, you need to understand the following issues.

A window message can return up to five values. The first value, WIN-MSG-HANDLE identifies the window handle of the window that generated the message. The second value, WIN-MSG-ID, identifies the type of message (ID). The significance of the other three parameters, WIN-LPARAM, WIN-WPARAM-L, and WIN-WPARAM-H, will depend on the message ID. These values are passed as individual parameters to the object/event procedure.

Your code to interpret these messages would resemble the following:

IF WIN-MSG-HANDLE = MY-WINDOW-HANDLE
AND WIN-MSG-ID = THE-MSG-ID-I-WANT
PERFORM MY-EVENT-HANDLING.

The MY-EVENT-HANDLING routine would interpret the additional parameters. These parameters are documented in this Help file in the detailed explanation of each message.

If you are using ActiveX controls, the message interpretation is more elaborate. ActiveX control message interpretation is automatically handled by the WOW Extensions event-handling logic. Liant strongly recommends that you do not alter this logic or imitate it in code that you write for yourself.


Classes of Messages

A window class is a set of attributes that defines how a window looks and behaves. Before an application can create and use a window, a window class must have been created and registered for that window. WOW Extensions automatically creates all the window classes you need.

The different control classes have messages that are specific to that class. For example, messages specific to edit box controls begin with the prefix EM-. Similarly, messages specific to buttons begin with the prefix BM-; for combo boxes, the prefix is CB-; for list boxes, the prefix is LB-.

Note Command buttons, check boxes, and option buttons all belong to the Button class (prefix BM-) and use the same messages. Scroll bars have no messages of their own; however, they utilize the general window messages with the prefix WM-.


Categories of Messages Used in WOW Extensions

For documentation purposes, the messages used in WOW Extensions have been grouped into four categories. For more information, click on one of the following topics:

· Object-Manipulation Messages

· Event-Triggering Messages

· Automatically-Processed Messages

· Information-Only Messages


Object-Manipulation Messages

See Also

This section describes the Windows messages that a WOW application sends to forms and controls (objects) in order to manipulate them.

Every Windows message contains the handle of the window for which the message is intended and the ID number of the message. One or two additional parameters may also be included; their meanings depend on the type of message being sent. Many messages return a value to indicate the result of the message being processed. WOW Extensions provides shortcuts for object-manipulation messages so that it is easier to understand what the parameters are for a particular message. The available shortcuts are listed in the Code Templates tree on the WOW Designer window.

For example, if you were to go to Microsoft’s MSDN Library on the Internet and look up the Animation Control message, ACM-PLAY, you would see something that resembles the following:

To send this message, call the sendmessage function as follows.
lResult = SendMessage( // returns LRESULT in lResult
(HWND) hWndControl, // handle to destination control
(UINT) ACM_PLAY, // message ID
(WPARAM) wParam, // = (WPARAM) (UINT) cRepeat
(LPARAM) lParam // = (LPARAM) MAKELONG(wFrom, wTo)
);

The code shortcut provided by WOW for the ACM-PLAY message defines these message parameters for you:

Call SendMessage Using Win-Return Wnd-H ACM-Play RepeatCount LastFrame
FirstFrame.
* Win-Return receives 1 if function is successful
* Wnd-H = handle of animation control
* RepeatCount = # of times to play, -1 to repeat
* LastFrame = zero based index of last frame to play, -1 means
the last frame
* FirstFrame = zero based index of first frame to play.

To view descriptions of the object-manipulation messages used by WOW Extensions, click one of the following topics:

· Animation Control Messages

· Button Messages

· Combo Box Messages

· Edit Box Messages

· List Box Messages

· Progress Bar Messages

· Send Messages


Animation Control Messages

See Also

The following table summarizes the animation control messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
ACM-OPEN | Opens an AVI clip and displays its first frame in an animation control.
ACM-PLAY | Plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing.
ACM-STOP | Stops playing an AVI clip in an animation control.


ACM-OPEN

Object Manipulation Message: Animation Control

An application sends an ACM-OPEN message to open an AVI clip and displays its first frame in an animation control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H ACM-OPEN 0 FILENAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful or zero if it is unsuccessful.
WND-H | PIC 9(10) BINARY(8) | The handle of the animation control to which the message will be sent.
ACM-OPEN | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
0 | windows.cpy | Required field.
FILENAME | alphanumeric | The name of the AVI file to open.


ACM-PLAY

Object Manipulation Message: Animation Control

An application sends an ACM-PLAY message to play an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H ACM-PLAY
REPEATCOUNT LASTFRAME FIRSTFRAME.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful or zero if it is unsuccessful.
WND-H | PIC 9(10) BINARY(8) | The handle of the animation control to which the message will be sent.
ACM-PLAY | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
REPEATCOUNT | numeric | Specifies the number of times to play the AVI clip. The value -1 indicates that the clip will play indefinitely.
LASTFRAME | numeric | The zero-based index of last frame of the AVI clip to play. -1 means the last frame.
FIRSTFRAME | numeric | The zero-based index of first frame of the AVI clip to play.


ACM-STOP

Object Manipulation Message: Animation Control

An application sends an ACM-STOP message to stop playing an AVI clip in an animation control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H ACM-STOP.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the animation control to which the message will be sent.
ACM-STOP | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


Button Messages

See Also

The following table summarizes the button messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
BM-GETCHECK | Retrieves the check state of a button control.
BM-GETSTATE | Retrieves the state of a button control.
BM-SETCHECK | Checks state of a button control.
BM-SETSTATE | Sets the highlight state of a button control.
BM-SETSTYLE | Changes the style of a button control.


BM-GETCHECK

Object Manipulation Message: Button

An application sends a BM-GETCHECK message to retrieve the check state of a button control. This message will only work with buttons created with the BS-AUTOCHECKBOX, BS-AUTORADIOBUTTON, BS-AUTO3STATE, BS-CHECKBOX, BS-RADIOBUTTON, or BS-3STATE style. If the button has any other style, the return value is 0.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN BTN-H BM-GETCHECK.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value indicates the check state of the button and has one of the following values:
 | Value | Meaning
 | 0 | Button state is unchecked.
 | 1 | Button state is checked.
 | 2 | Button state is indeterminate (applies only if the button has the BS-3STATE or BS-AUTO3STATE style).
BTN-H | PIC 9(10) BINARY(8) | The handle of the button control to which the message will be sent.
BM-GETCHECK | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


BM-GETSTATE

Object Manipulation Message: Button

An application sends a BM-GETSTATE message to retrieve the state of a button control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN BTN-H BM-GETSTATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the current state of the button. You can use the following masks to extract information about the state:
 | Mask | Description
 | 0x0003 | Specifies the check state (radio buttons and check boxes, only). A value of BST-UNCHECKED indicates the button is unchecked. A value of BST-CHECKED indicates the button is checked. A radio button is checked when it contains a dot; a check box is checked when it contains an X. A value of BST-INDETERMINATE indicates the check state is indeterminate (applies only if the button has the BS-3STATE or BS-AUTO3STATE style). A three-state check box is grayed when its state is indeterminate.
 | BST-CHECKED | Indicates the button is checked,
 | BST-FOCUS | Specifies the focus state. A nonzero value indicates that the button has the keyboard focus.
 | BST-INDETERMINATE | Indicates the button is grayed because the state of the button is indeterminate. This value applies only if the button has the BS-3STATE or BS-AUTO3STATE style.
 | BST-PUSHED | Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.
 | BST-UNCHECKED | Indicates the button is unchecked. Same as a return value of zero.
BTN-H | PIC 9(10) BINARY(8) | The handle of the button control to which the message will be sent.
BM-GETSTATE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent. The ID of the message to be sent.


BM-SETCHECK

Object Manipulation Message: Button

An application sends a BM-SETCHECK message to set the check state of a button control. The BM-SETCHECK message has no effect on push buttons.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN BTN-H BM-SETCHECK STATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always 0.
BTN-H | PIC 9(10) BINARY(8) | The handle of the button control to which the message will be sent.
BM-SETCHECK | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
STATE | numeric | Specifies the check state. This parameter can be one of the following values:
 | Value | Meaning
 | 0 | Set the button state to unchecked.
 | 1 | Set the button state to checked.
 | 2 | Set the button state to indeterminate. This value can be used only if the button has the BS-3STATE or BS-AUTO3STATE style.


BM-SETSTATE

Object Manipulation Message: Button

An application sends a BM-SETSTATE message to set the highlight state of a button control. Highlighting affects the exterior of a button. It has no effect on the check state of a radio button or check box.

A button is automatically highlighted when the user presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H BM-SETSTATE STATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always 0.
BTN-H | PIC 9(10) BINARY(8) | The handle of the button control to which the message will be sent.
BM-SETSTATE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
STATE | windows.cpy | Specifies whether the button is to be highlighted. A nonzero value highlights the button. A zero value removes any highlighting.


BM-SETSTYLE

Object Manipulation Message: Button

An application sends a BM-SETSTYLE message to change the style of a button control. Unlike BM-SETCHECK and BM-SETSTATE, BM-SETSTYLE does not have a corresponding message to retrieve the current style. Use the GETWINDOWLONG function with the GWL-STYLE offset to retrieve the complete button style. The low word of the complete button style is the button-specific style.

An application should not attempt to change a button’s type (for example, changing a radio button to a check box).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN BTN-H BM-SETSTYLE NEW-STYLE REDRAW.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always 0.
BTN-H | PIC 9(10) BINARY(8) | The handle of the button control to which the message will be sent.
BM-SETSTYLE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
NEW-STYLE | windows.cpy | Specifies the button style. For a list of possible buttons styles, see the note that follows.
REDRAW | windows.cpy | Specifies whether the button is to be redrawn. A value of WIN-TRUE redraws the button. A value of WIN-FALSE does not redraw the button.

Note Information regarding button styles can be found on the Internet at http://msdn.microsoft.com/library/. Periodically, Microsoft reorganizes the MSDN information on the website. Use the search capability to find information on the requested topic.


Combo Box Messages

See Also

The following table summarizes the combo box messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
CB-ADDSTRING | Adds a string to the list box portion of a combo box control.
CB-DELETESTRING | Deletes a string in the list box portion of a combo box control.
CB-DIR | Adds a list of filenames to the list box portion of a combo box control.
CB-FINDSTRING | Searches the list box portion of a combo box control for an item that begins with the characters in a specified string.
CB-FINDSTRINGEXACT | Finds the first list box string in a combo box control that matches the string specified in the SEARCH-STRING parameter.
CB-GETCOUNT | Retrieves the number of items in the list box portion of a combo box control.
CB-GETCURSEL | Retrieves the index of the currently selected item, if any, in the list box portion of a combo box control.
CB-GETDROPPEDCONTROLRECT | Retrieves the screen coordinates of the visible (dropped-down) list box portion of a combo box control.
CB-GETDROPPEDSTATE | Determines whether the list box portion of a combo box control is visible (that is, dropped down).
CB-GETEDITSEL | Retrieves the starting and ending character positions of the current selection in the edit box portion of a combo box control.
CB-GETEXTENDEDUI | Determines whether a combo box control has the default user interface (Simple style) or the extended user interface (Dropdown List box or Dropdown Combo box style).
CB-GETITEMHEIGHT | Retrieves the height of list items in a combo box control or the height of the edit box (or static text box) portions of a combo box control.
CB-GETLBTEXT | Retrieves a string from the list box portion of a combo box control.
CB-GETLBTEXTLEN | Retrieves the length of a string in the list box portion of a combo box control.
CB-INSERTSTRING | Inserts a string into the list box portion of a combo box control.
CB-LIMITTEXT | Limits the length of the text that the user may type in the edit box portion of a combo box control.
CB-RESETCONTENT | Removes all items from the list box and edit box (or static text box) portions of a combo box control.
CB-SELECTSTRING | Searches the list box portion of a combo box control for an item that begins with the characters in a specified string.
CB-SETCURSEL | Selects a string in the list box portion of a combo box control.
CB-SETEDITSEL | Selects characters in the edit box portion of a combo box control.
CB-SETEXTENDEDUI | Selects either the default user interface (Simple style) or the extended user interface (Dropdown List box or Dropdown Combo box style) for a combo box control.
CB-SETITEMHEIGHT | Sets the height of the list items in a combo box control or the height of the edit box (or static text box) portions of a combo box control.
CB-SHOWDROPDOWN | Shows or hides the list box portion of a combo box control that has the Dropdown List box or Dropdown Combo box style.


CB-ADDSTRING

Object Manipulation Message: Combo Box

An application sends a CB-ADDSTRING message to add a string to the list box portion of a combo box control. If the combo box does not have the CBS-SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

The return value is the zero-based index to the string in the list box of the combo box. The return value is CB-ERR if an error occurs; the return value is CB-ERRSPACE if insufficient space is available to store the new string.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-ADDSTRING 0 NEW-ENTRY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index to the string in the list box of the combo box. The return value is CB-ERR is an error occurs; the return value is CB-ERRSPACE if insufficient space is available to store the new string.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-ADDSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
0 | Not used. | Must be zero.
NEW-ENTRY | alphanumeric | The string to be added.


CB-DELETESTRING

Object Manipulation Message: Combo Box

An application sends a CB-DELETESTRING message to delete a string in the list box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-DELETESTRING INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a count of the strings remaining in the list. The return value is CB-ERR if the INDEX-NUM parameter specifies an index greater than the number of items in the list.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-DELETESTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the string to delete.


CB-DIR

Object Manipulation Message: Combo Box

An application sends a CB-DIR message to add a list of filenames to the list box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-DIR
FILE-ATTRS FILE-SPEC.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the last filename added to the list. The return value is CB-ERR if an error occurs. The return value is CB-ERRSPACE if insufficient space is available to store the new strings.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-DIR | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
FILE-ATTRS |  | Specifies the attributes of the files to be added to the list box. It can be one or more of the following styles.
 | Value | Meaning
 | DDL-ARCHIVE | List includes archived files.
 | DDL-DIRECTORY | List includes subdirectories, which are enclosed in square brackets ([ ]).
 | DDL-DRIVES | List includes all drives that match the name specified by the FILE-SPEC parameter are included. If the DDL-DRIVES flag is set, the DDL-EXCLUSIVE flag is set automatically. Therefore, to create a directory listing that includes drives and files, the developer must send this message twice: once with the DDL-DRIVES flag set and once with the flags for the rest of the list.
 | DDL-EXCLUSIVE | List includes only files with the specified attributes. By default, read-write files are listed even if DDL-READWRITE is not specified.
 | DDL-HIDDEN | List includes hidden files.
 | DDL-READONLY | List includes read-only files.
 | DDL-READWRITE | List includes read-write files with no additional attributes. This is the default.
 | DDL-SYSTEM | List includes system files.
FILE-SPEC |  | Pointer to a null-terminated string that specifies an absolute path, relative path, or filename. An absolute path can begin with a drive letter (for example, d:\) or a UNC name (for example, \\ machinename\ sharename). If the string specifies a filename or directory that has the attributes specified by the FILE-ATTRS parameter, the filename or directory is added to the list. If the filename or directory name contains wildcard characters (? or *), all files or directories that match the wildcard expression and have the attributes specified by the FILE-ATTRS parameter are added to the list displayed in the combo box.


CB-FINDSTRING

Object Manipulation Message: Combo Box

An application sends a CB-FINDSTRING message to search the list box portion of a combo box control for an item that begins with the characters in a specified string.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-FINDSTRING
INDEX-START SEARCH-STRING.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the matching item, or it is CB-ERR if the search was unsuccessful.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-FINDSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | numeric | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START is -1, the entire list box is searched from the beginning.
SEARCH-STRING | alphanumeric | Points to the null-terminated string that contains the characters for which to search. The search is not case-sensitive, so this string can contain any combination of uppercase and lowercase letters.


CB-FINDSTRINGEXACT

Object Manipulation Message: Combo Box

An application sends a CB-FINDSTRINGEXACT message to find the first list box string (in a combo box control) that matches the string specified in the SEARCH-STRING parameter.

Calling Sequence

CALL SENDMESSSAGE USING WIN-RETURN CB-H CB-FINDSTRINGEXACT
INDEX-START SEARCH-VALUE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the matching item, or it is CB-ERR if the search was unsuccessful.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-FINDSTRINGEXACT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | numeric | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START -1, the entire list box is searched from the beginning.
SEARCH-VALUE | alphanumeric | Pointer to the null-terminated string for which to search. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.


CB-GETCOUNT

Object Manipulation Message: Combo Box

An application sends a CB-GETCOUNT message to retrieve the number of items in the list box portion of a combo box control. The returned count is one greater than the index value of the last item (the index is zero-based).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETCOUNT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of items in the list box.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETCOUNT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-GETCURSEL

Object Manipulation Message: Combo Box

An application sends a CB-GETCURSEL message to retrieve the index of the currently selected item, if any, in the list box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETCURSEL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the currently selected item, or it is CB-ERR if no item is selected.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETCURSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-GETDROPPEDCONTROLRECT

Object Manipulation Message: Combo Box

An application sends a CB-GETDROPPEDCONTROLRECT message to retrieve the screen coordinates of the visible (dropped-down) list box portion of a combo box control. The return value is always CB-OKAY.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H
CB-GETDROPPEDCONTROLRECT RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always CB-OKAY.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETDROPPEDCONTROLRECT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
RECT | windows.cpy | A pointer to the Rect structure that is to receive the coordinates of the combo box in its dropped-down state. The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.


CB-GETDROPPEDSTATE

Object Manipulation Message: Combo Box

An application sends a CB-GETDROPPEDSTATE message to determine whether the list box portion of a combo box control is visible (dropped down).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETDROPPEDSTATE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the list box is visible; otherwise, it is zero.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETDROPPEDSTATE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-GETEDITSEL

Object Manipulation Message: Combo Box

An application sends a CB-GETEDITSEL message to retrieve the starting and ending character positions of the current selection in the edit box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETEDITSEL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a double word value that contains the starting position in the low-order word and the position of the first non-selected character after the end of the selection in the high-order word.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETEDITSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-GETEXTENDEDUI

Object Manipulation Message: Combo Box

An application sends a CB-GETEXTENDEDUI message to determine whether a combo box control has the default user interface or the extended user interface.

The extended user interface differs from the default user interface in the following ways:

· Clicking the static control displays the list box (CBS-DROPDOWNLIST style only).

· Pressing the DOWN ARROW key displays the list box (F4 is disabled).

· Scrolling in the static control is disabled when the item list is not visible (arrow keys are disabled).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETEXTENDEDUI.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the combo box has the extended user interface; otherwise, it is zero.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETEXTENDEDUI | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-GETITEMHEIGHT

Object Manipulation Message: Combo Box

An application sends a CB-GETITEMHEIGHT message to retrieve the height of list items in a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETITEMHEIGHT INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the height, in pixels, of the list items in a combo box. The return value is the height of the edit box (or static text box) portions of the combo box if index is -1. The return value is CB-ERR if an error occurred.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETITEMHEIGHT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the component of the combo box whose height is to be retrieved. If the index parameter is -1, the height of the edit box (or static text box) portions of the combo box is retrieved.


CB-GETLBTEXT

Object Manipulation Message: Combo Box

An application sends a CB-GETLBTEXT message to retrieve a string from the list box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETLBTEXT
INDEX-NUM TEXT-AREA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length of the string, in bytes. If the index parameter does not specify a valid index, the return value is CB-ERR.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETLBTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the string to retrieve.
TEXT-AREA | alphanumeric | Pointer to the buffer that receives the string. The buffer must have sufficient space for the string. A CB-GETLBTEXTLEN message can be sent before the CB-GETLBTEXT message to retrieve the length of the string. If it is an ANSI string this is the number of bytes, but if it is a Unicode string this is the number of characters.


CB-GETLBTEXTLEN

Object Manipulation Message: Combo Box

An application sends a CB-GETLBTEXTLEN message to retrieve the length of a string in the list box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-GETLBTEXTLEN INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length of the string, in bytes. If the index parameter does not specify a valid index, the return value is CB-ERR.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-GETLBTEXTLEN | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the string.


CB-INSERTSTRING

Object Manipulation Message: Combo Box

An application sends a CB-INSERTSTRING message to insert a string into the list box portion of a combo box control. Unlike the CB-ADDSTRING message, the CB-INSERTSTRING message does not cause a list with the CBS-SORT style to be sorted.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-INSERTSTRING
INDEX-NUM NEW-ENTRY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the position at which the string was inserted. The return value is CB-ERR if an error occurs. The return value is CB-ERRSPACE if insufficient space is available to store the new string.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-INSERTSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the position at which to insert the string. If the value of this parameter is -1, the string is added to the end of the list.
NEW-ENTRY | alphanumeric | Pointer to the null-terminated string that is to be inserted.


CB-LIMITTEXT

Object Manipulation Message: Combo Box

An application sends a CB-LIMITTEXT message to limit the length of the text that the user may type in the edit box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-LIMITTEXT TEXT-LIMIT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is 1 if the message is successful. If this message is sent to a combo box with the style CBS-DROPDOWNLIST, the return value is CB-ERR.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-LIMITTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
TEXT-LIMIT | numeric | Specifies the length, in bytes, of the text the user can enter. If the value of this parameter is zero, the text length is set to 65,535 bytes.


CB-RESETCONTENT

Object Manipulation Message: Combo Box

An application sends a CB-RESETCONTENT message to remove all items from the list box and edit box portion of a combo box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-RESETCONTENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always CB-OKAY.
CB-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
CB-RESETCONTENT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


CB-SELECTSTRING

Object Manipulation Message: Combo Box

An application sends a CB-SELECTSTRING message to search the list box portion of a combo box control for an item that begins with the characters in a specified string. If a matching item is found, the item is selected and copied to the edit box portion. A string is selected only if its initial characters (from the starting point) match the characters in the prefix string.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SELECTSTRING
INDEX-START SEL-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the selected item if the string was found. The return value is CB-ERR and the current selection is not changed if the search was unsuccessful.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-SELECTSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | numeric | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the lists box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START is -1, the entire list box is searched from the beginning.
SEL-TEXT | alphanumeric | Pointer to the null-terminated string that contains the string for which to search. The search is not case-sensitive, so this string can contain any combination of uppercase and lowercase letters.


CB-SETCURSEL

Object Manipulation Message: Combo Box

An application sends a CB-SETCURSEL message to select a string in the list box portion of a combo box control. If necessary, the list box scrolls the string into view (if the list box is visible). The text in the edit box portion of the combo box is changed to reflect the new selection. Any previous selection in the list box is removed.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SETCURSEL
INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the item selected if the message is successful. The return value is CB-ERR if the index parameter is greater than the number of items in the list or if index is set to -1 (which clears the selection).
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-SETCURSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the string to select. If the index parameter is -1, any current selection in the list box portion is removed and the edit box portion is cleared.


CB-SETEDITSEL

Object Manipulation Message: Combo Box

An application sends a CB-SETEDITSEL message to select characters in the edit box portion of a combo box control.

The positions are zero-based. To select the first character of the edit box, you specify a starting position of zero. The ending position is for the character just after the last character to select. For example, to select the first four characters of the edit box, you would use a starting position of 0 and an ending position of 4.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SETEDITSEL
START-POS END-POS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the message is successful. It is CB-ERR if the message is sent to a combo box with the CBS-DROPDOWNLIST style.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-SETEDITSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
START-POS | numeric | Specifies the starting position. If the value of this parameter is set to -1, the selection, if any, is removed.
END-POS | numeric | Specifies the ending position. If the value of this parameter is set to -1, all text from the starting position to the last character in the edit box is selected.


CB-SETEXTENDEDUI

Object Manipulation Message: Combo Box

An application sends a CB-SETEXTENDEDUI message to select either the default user interface or the extended user interface for a combo box control that has the CBS-DROPDOWN or CBS-DROPDOWNLIST style.

The extended user interface differs from the default user interface in the following ways:

· Clicking the static control displays the list box (CBS-DROPDOWNLIST style only).

· Pressing the DOWN ARROW key displays the list box (F4 is disabled).

· Scrolling in the static control is disabled when the item list is not visible (the arrow keys are disabled).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SETEXTENDEDUI
EXTENDED-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is CB-OKAY if the operation is successful, or it is CB-ERR if an error occurred.
CB-H | PIC 9(10) BINARY(8) | The handle of the combo box to which the message will be sent.
CB-SETEXTENDEDUI | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
EXTENDED-FLAG | numeric | Specifies whether the combo box should use the extended user interface or the default user interface. A value of WIN-TRUE selects the extended user interface; a value of WIN-FALSE selects the standard user interface.


CB-SETITEMHEIGHT

Object Manipulation Message: Combo Box

An application sends a CB-SETITEMHEIGHT message to set the height of list items in a combo box control or the height of the edit box (or static text box) portion of a combo box control. The height of the edit box (or static text box) portion of the combo box control is set independently of the height of the list items. An application must ensure that the height of the edit box (or static text box) portion isn’t smaller than the height of a particular list box item.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SETITEMHEIGHT
INDEX-NUM HEIGHT.

Parameter

Declaration

Description

WIN-RETURN

numeric

The return value is CB-ERR if the index or height is invalid.

CB-H

PIC 9(10) BINARY(8)

The handle of the combo box to which the message will be sent.

CB-SETITEMHEIGHT

Possible values are declared as 78-level descriptions in windows.cpy.

The ID of the message to be sent.

INDEX-NUM

numeric

Specifies whether the height of list items or the height of the edit box (or static text box) portions of the combo box is set.

If the combo box has the CBS-OWNERDRAWVARIABLE style, the index parameter specifies the zero-based index of the list item whose height is to be set; otherwise, index must be zero and the height of all list items will be set.

If index is -1, the height of the edit box or static text box portions of the combo box is to be set.

HEIGHT

numeric

Specifies the height, in pixels, of the combo box component identified by index.


CB-SHOWDROPDOWN

Object Manipulation Message: Combo Box

An application sends a CB-SHOWDROPDOWN message to show or hide the list box portion of a combo box control that has the CBS-DROPDOWN or CBS-DROPDOWNLIST style. This message has no effect on a combo box created with the CBS-SIMPLE style.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CB-H CB-SHOWDROPDOWN
SHOW-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always nonzero.
CB-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
CB-SHOWDROPDOWN | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
SHOW-FLAG | numeric | Specifies whether the drop-down list box is to be shown or hidden. A value of WIN-TRUE shows the list box. A value of WIN-FALSE hides the list box.


Edit Box Messages

See Also

The following table summarizes the edit box messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
EM-CANUNDO | Determines whether there are any actions in an edit box control's undo queue.
EM-EMPTYUNDOBUFFER | Resets the undo flag of an edit box control.
EM-FMTLINES | Sets the inclusion of soft line break characters on or off within a multiline edit box control.
EM-GETFIRSTVISIBLELINE | Determines the topmost visible line in an edit box control.
EM-GETLINE | Retrieves a line of text from an edit box control.
EM-GETLINECOUNT | Retrieves the number of lines in a multiline edit box control.
EM-GETMODIFY | Determines whether the contents of an edit box control have been modified.
EM-GETPASSWORDCHAR | Retrieves the password character displayed in an edit box control when the user enters text.
EM-GETRECT | Retrieves the formatting rectangle of an edit box control.
EM-GETSEL | Retrieves the starting and ending character positions of the current selection in an edit box control.
EM-LIMITTEXT | Limits the length of the text the user can enter into an edit box control.
EM-LINEFROMCHAR | Retrieves the line number of the line that contains the specified character index.
EM-LINEINDEX | Retrieves the character index of a line within a multiline edit box control.
EM-LINELENGTH | Retrieves the length of a line in an edit box control.
EM-LINESCROLL | Scrolls the text of a multiline edit box control.
EM-REPLACESEL | Replaces the current selection in an edit box control with the text specified by the NEW-TEXT parameter.
EM-SETMODIFY | Sets or clears the modification flag for an edit box control.
EM-SETPASSWORDCHAR | Sets or removes a password character displayed in an edit box control when the user types text.
EM-SETREADONLY | Sets the read-only state of an edit box control.
EM-SETRECT | Sets the formatting rectangle of a multiline edit box control.
EM-SETRECTNP | Sets the formatting rectangle of a multiline edit box control without repainting it.
EM-SETSEL | Selects a range of characters in an edit box control.
EM-SETTABSTOPS | Sets tab stops in a multiline edit box control.
EM-UNDO | Undoes the last edit box control operation.


EM-CANUNDO

Object Manipulation Message: Edit Box

An application sends an EM-CANUNDO message to determine whether there are any actions in the undo queue of an edit box control. If the undo queue is not empty, you send the EM-UNDO message to the control to undo the most recent operation.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-CANUNDO.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the last edit operation can be undone, or it is zero if the last edit operation cannot be undone.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-CANUNDO | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-EMPTYUNDOBUFFER

Object Manipulation Message: Edit Box

An application sends an EM-EMPTYUNDOBUFFER message to reset (clear) the undo flag of an edit box control. The undo flag is set whenever an operation within the edit box can be undone.

The undo flag is automatically cleared whenever the edit box receives a WM-SETTEXT message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-EMPTYUNDOBUFFER.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-EMPTYUNDOBUFFER | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-FMTLINES

Object Manipulation Message: Edit Box

An application sends an EM-FMTLINES message to set the inclusion of soft line break characters on or off within a multiline edit box control. A soft line break consists of two carriage returns and a linefeed inserted at the end of a line that is broken because of word wrapping.

This message is processed only by multiline edit box controls.

This message affects only the buffer returned by the text returned by the WM-GETTEXT message. It has no effect on the display of the text within the edit box.

A line that ends with a hard line break is not affected by the EM-FMTLINES message. A hard line break consists of one carriage return and a linefeed.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-FMTLINES LB-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is identical to the LB-FLAG parameter.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-FMTLINES | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
LB-FLAG | windows.cpy | Specifies whether soft line break characters are to be inserted. A value of WIN-TRUE inserts the characters; a value of WIN-FALSE removes them.


EM-GETFIRSTVISIBLELINE

Object Manipulation Message: Edit Box

An application sends an EM-GETFIRSTVISIBLELINE message to determine the topmost visible line in an edit box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H
EM-GETFIRSTVISIBLELINE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the topmost visible line. For single-line edit boxes, the return value is zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETFIRSTVISIBLELINE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-GETLINE

Object Manipulation Message: Edit Box

An application sends an EM-GETLINE message to retrieve a line of text from an edit box control and places it in a specified buffer.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETLINE
LINE-NUM TEXT-AREA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of bytes actually copied. The return value is 0 if the line number specified by the LINE-NUM parameter is greater than the number of lines in the edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETLINE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
LINE-NUM | numeric | Specifies the line number of the line to retrieve from a multiline edit box. Line numbers are zero-based; a value of zero specifies the first line. This parameter is ignored by a single-line edit box.
TEXT-AREA | alphanumeric | Pointer to the buffer that receives a copy of the line. For ANSI text, this is the number of bytes; for Unicode text, this is the number of characters. The size in the first word is overwritten by the copied line.


EM-GETLINECOUNT

Object Manipulation Message: Edit Box

An application sends an EM-GETLINECOUNT message to retrieve the number of lines in a multiline edit box control.

This message is processed only by multiline edit box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETLINECOUNT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of lines in the multiline edit box. If no text is in the edit box, the return value is 1.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETLINECOUNT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-GETMODIFY

Object Manipulation Message: Edit Box

An application sends an EM-GETMODIFY message to determine whether the contents of an edit box control have been modified.

Windows maintains an internal flag indicating whether the contents of the edit box have been changed. This flag is cleared when the edit box is first created; or an EM-SETMODIFY message can be sent to clear the flag.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETMODIFY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the edit box contents have been modified, or it is zero if the contents have remained unchanged.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETMODIFY | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-GETPASSWORDCHAR

Object Manipulation Message: Edit Box

An application sends an EM-GETPASSWORDCHAR message to retrieve the password character displayed in an edit box control when the user enters text.

If the edit box is created with the ES-PASSWORD style, the default password character is set to an asterisk (*).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETPASSWORDCHAR.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value specifies the character to be displayed in place of the character typed by the user. The return value is 0 if no password character exists.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETPASSWORDCHAR | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-GETRECT

Object Manipulation Message: Edit Box

An application sends an EM-GETRECT message to retrieve the formatting rectangle of an edit box control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit box window.

The formatting rectangle of a multiline edit box control can be modified by the EM-SETRECT and EM-SETRECTNP messages.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETRECT RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is not a meaningful value.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-GETRECT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
RECT | windows.cpy | A pointer to the RECT structure that receives the formatting rectangle. The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.


EM-GETSEL

Object Manipulation Message: Edit Box

An application sends an EM-GETSEL message to get the starting and ending character positions of the current selection in an edit box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-GETSEL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a double word value that contains the starting position in the low-order word and the position of the first non-selected character after the end of the selection in the high-order word.
ED-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
EM-GETSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


EM-LIMITTEXT

Object Manipulation Message: Edit Box

An application sends an EM-LIMITTEXT message to limit the length of the text the user can enter into an edit box control.

The EM-LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit box when the message is sent, nor does it affect the length of text copied to the edit box by the WM-SETTEXT message.

If an application uses the WM-SETTEXT message to place more text into an edit box than is specified in the EM-LIMITTEXT message, the user can edit the entire contents of the edit box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-LIMITTEXT MAX-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-LIMITTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
MAX-TEXT | numeric | Specifies the length, in bytes, of the text the user can enter. If the value of this parameter is zero, the text length is set to 65,535 bytes.


EM-LINEFROMCHAR

Object Manipulation Message: Edit Box

An application sends an EM-LINEFROMCHAR message to retrieve the line number of the line that contains the specified character index. A character index is the number of characters from the beginning of the edit box control.

This message is processed only by multiline edit box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H
EM-LINEFROMCHAR CHAR-INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based line number of the line containing the character index specified by CHAR-INDEX.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-LINEFROMCHAR | windows.cpy | The ID of the message to be sent.
CHAR-INDEX | numeric | Specifies the character index of the character contained in the line whose number is to be retrieved. If the CHAR-INDEX parameter is -1, either the line number of the current line (the line containing the caret) is retrieved or, if there is a selection, the line number of the line containing the beginning of the selection is retrieved.


EM-LINEINDEX

Object Manipulation Message: Edit Box

An application sends an EM-LINEINDEX message to retrieve the character index of a line within a multiline edit box control. The character index is the number of characters from the beginning of the edit box to the specified line.

This message is processed only by multiline edit box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H
EM-LINEINDEX LINE-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the character index of the line specified in the LINE-NUM parameter, or it is -1 if the specified line number is greater than the number of lines in the edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-LINEINDEX | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
LINE-NUM | numeric | Specifies the zero-based line number. A value of -1 specifies the current line number (the line that contains the caret).


EM-LINELENGTH

Object Manipulation Message: Edit Box

An application sends an EM-LINELENGTH message to retrieve the length of a line in an edit box control.

Use the EM-LINEINDEX message to retrieve a character index for a given line number within a multiline edit box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H
EM-LINELENGTH CHAR-INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length, in bytes, of the line specified by the CHAR-INDEX parameter when an EM-LINELENGTH message is sent to a multiline edit box. The return value is the length, in bytes, of the text in the edit box when an EM-LINELENGTH message is sent to a single-line edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-LINELENGTH | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
CHAR-INDEX | numeric | Specifies the character index of a character in the line whose length is to be retrieved when EM-LINELENGTH is sent to a multiline edit box. If the value of this parameter is -1, the message returns the number of unselected characters on lines containing selected characters. For example, if the selection extended from the fourth character of one line through the eighth character from the end of the next line, the return value would be 10 (three characters on the first line and seven on the next). When EM-LINELENGTH is sent to a single-line edit box, this parameter is ignored.


EM-LINESCROLL

Object Manipulation Message: Edit Box

An application sends an EM-LINESCROLL message to scroll the text of a multiline edit box control.

This message is processed only by multiline edit box controls.

The edit box does not scroll vertically past the last line of text in the edit box. If the current line plus the number of lines specified by the DV parameter exceeds the total number of lines in the edit box, the value is adjusted so that the last line of the edit box is scrolled to the top of the edit box window.

The EM-LINESCROLL message can be used to scroll horizontally past the last character of any line.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-LINESCROLL 0
VERT-SCROLL HORIZ-SCROLL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the message is sent to a multiline edit box, or it is zero if the message is sent to a single-line edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-LINESCROLL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
VERT-SCROLL | numeric | Specifies the number of lines to scroll vertically.
HORIZ-SCROLL | numeric | Specifies the number of character positions to scroll horizontally. This value is ignored if the edit box has either the ES-RIGHT or ES-CENTER style.


EM-REPLACESEL

Object Manipulation Message: Edit Box

An application sends an EM-REPLACESEL message to replace the current selection in an edit box control with the text specified by the NEW-TEXT parameter.

Use the EM-REPLACESEL message when you want to replace only a portion of the text in an edit box. If you want to replace all of the text, use the WM-SETTEXT message.

If there is no current selection, the replacement text is inserted at the current cursor location.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-REPLACESEL 0 NEW-TEXT.

Parameter | Declaration | Description
WIN-RETURN | Numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-REPLACESEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
0 | Not used. | Must be zero.
NEW-TEXT | alphanumeric | A string containing the replacement text.


EM-SETMODIFY

Object Manipulation Message: Edit Box

An application sends an EM-SETMODIFY message to set or clear the modification flag for an edit box control. The modification flag indicates whether the text within the edit box has been modified. It is automatically set whenever the user changes the text. An EM-GETMODIFY message can be sent to retrieve the value of the modification flag.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETMODIFY MOD-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETMODIFY | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
MOD-FLAG | windows.cpy | Specifies the new value for the modification flag. A value of WIN-TRUE indicates the text has been modified; a value of WIN-FALSE indicates it has not been modified.


EM-SETPASSWORDCHAR

Object Manipulation Message: Edit Box

An application sends an EM-SETPASSWORDCHAR message to set or remove a password character displayed in an edit box control when the user types text. When a password character is set, that character is displayed for each character the user types.

This message has no effect on a multiline edit box control.

When the EM-SETPASSWORDCHAR message is received by an edit box, the edit box redraws all visible characters by using the character specified by the PWD-CHAR parameter.

If the edit box control is created with the ES-PASSWORD style, the default password character is set to an asterisk (*). This style is removed if an EM-SETPASSWORDCHAR message is sent with the PWD-CHAR parameter set to zero.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H
EM-SETPASSWORDCHAR PWD-CHAR.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the message is sent to an edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETPASSWORDCHAR | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
PWD-CHAR | alphanumeric | Specifies the character to be displayed in place of the character typed by the user. If the PWD-CHAR parameter is zero, the actual characters typed by the user are displayed.


EM-SETREADONLY

Object Manipulation Message: Edit Box

An application sends an EM-SETREADONLY message to set or remove the read-only state of an edit box control.

When the state of an edit box is set to read-only, the user cannot change the text within the edit box.

EM-SETREADONLY does not have a corresponding message to retrieve the current style. Calling the GETWINDOWLONG function with the GWL-STYLE offset retrieves the full control style.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETREADONLY
READONLY-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the operation is successful, or it is zero if an error occurs.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETREADONLY | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
READONLY-FLAG | windows.cpy | Specifies whether to set or remove the read-only state of the edit box. A value of WIN-TRUE sets the state to read-only; a value of WIN-FALSE sets the state to read/write.


EM-SETRECT

Object Manipulation Message: Edit Box

An application sends an EM-SETRECT message to set the formatting rectangle of a multiline edit box control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit box window. When the edit box is first created, the formatting rectangle is the same as the client area of the edit box window. By using the EM-SETRECT message, an application can make the formatting rectangle larger or smaller than the edit box window.

This message is processed only by multiline edit box controls.

The EM-SETRECT message causes the text of the edit box to be redrawn. To change the size of the formatting rectangle without redrawing the text, use the EM-SETRECTNP message.

If the edit box does not have a horizontal scroll bar, and the formatting rectangle is set to be larger than the edit box window, lines of text exceeding the width of the edit box window (but smaller than the width of the formatting rectangle) are clipped instead of wrapped.

If the edit box contains a border, the formatting rectangle is reduced by the size of the border. If you are adjusting the rectangle returned by an EM-GETRECT message, you must remove the size of the border before using the rectangle with the EM-SETRECT message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETRECT RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETRECT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
RECT | windows.cpy | A pointer to the RECT structure that specifies the new dimensions of the rectangle. The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.


EM-SETRECTNP

Object Manipulation Message: Edit Box

An application sends an EM-SETRECTNP message to set the formatting rectangle of a multiline edit box control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit box window. When the edit box is first created, the formatting rectangle is the same as the client area of the edit box window. By using the EM-SETRECTNP message, an application can make the formatting rectangle larger or smaller than the edit box window.

The EM-SETRECTNP message is identical to the EM-SETRECT message, except that the edit box window is not redrawn.

This message is processed only by multiline edit box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETRECTNP RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETRECTNP | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
RECT | windows.cpy | A pointer to the RECT structure that specifies the new dimensions of the rectangle. The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.


EM-SETSEL

Object Manipulation Message: Edit Box

An application sends an EM-SETSEL message to select a range of characters in an edit box control.

If the START-CHAR parameter is 0 and the END-CHAR parameter is -1, all the text in the edit box is selected. If START-CHAR is -1, any current selection is removed. The caret is placed at the end of the selection indicated by the greater of the two values END-CHAR and START-CHAR.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETSEL
START-CHAR END-CHAR.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the message is sent to an edit box.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
START-CHAR | numeric | Specifies the starting position.
END-CHAR | numeric | Specifies the ending position.


EM-SETTABSTOPS

Object Manipulation Message: Edit Box

An application sends an EM-SETTABSTOPS message to set tab stops in a multiline edit box control (MLE). When text is copied to an MLE, any tab character in the text causes space to be generated up to the next tab stop.

This message is processed only by MLEs.

The EM-SETTABSTOPS message does not automatically redraw the edit box window.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-SETTABSTOPS
TAB-COUNT TAB-STOPS.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the tabs were set; otherwise, the return value is zero.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-SETTABSTOPS | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
TAB-COUNT | numeric | Specifies the number of tab stops contained in the TAB-STOPS parameter. If the value of this parameter is 0, the TAB-STOPS parameter is 1 and tab stops are set at every n dialog box units, where n is the distance pointed to by the TAB-STOPS parameter. If the TAB-COUNT parameter is greater than 1, TAB-STOPS is an array of tab stops.
TAB-STOPS | PIC 9(4) COMP-4 occurs n times | An array of unsigned integers specifying the tab stops, in dialog box units. If the TAB-COUNT parameter is 1, TAB-STOPS is an unsigned integer containing the distance between all tab stops, in dialog units.


EM-UNDO

Object Manipulation Message: Edit Box

An application sends an EM-UNDO message to undo the last edit box control operation.

An undo operation can also be undone. For example, you can restore deleted text with the first EM-UNDO message and remove the text again with a second EM-UNDO message as long as there is no intervening edit box operation.

Note An application can also send the WM-UNDO message to an edit box to undo the last operation; however, the WM-UNDO specifically restores deleted text or deletes previously added text.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H EM-UNDO.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always nonzero for a single-line edit box. For a multiline edit box, the return value is nonzero if the undo operation is successful or zero if the undo operation fails.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
EM-UNDO | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


List Box Messages

See Also

The following table summarizes the list box messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
LB-ADDSTRING | Adds a string to a list box control.
LB-DELETESTRING | Deletes a string in a list box control.
LB-DIR | Adds a list of filenames to a list box control.
LB-FINDSTRING | Searches a list box control for an item that begins with the characters in a specified string.
LB-FINDSTRINGEXACT | Finds the first list box control string that matches the string specified in the SEARCH-TEXT parameter.
LB-GETCARETINDEX | Determines the index of the item that has the focus rectangle in a multiple-selection list box control.
LB-GETCOUNT | Retrieves the number of items in a list box control.
LB-GETCURSEL | Retrieves the index of the currently selected item, if any, in a single-selection list box control.
LB-GETHORIZONTALEXTENT | Retrieves from a list box control the width, in pixels, by which the list box can be scrolled horizontally if the list box has a horizontal scroll bar.
LB-GETITEMHEIGHT | Determines the height of items in a list box control.
LB-GETITEMRECT | Retrieves the dimensions of the rectangle that bounds an item as it is currently displayed in the list box control.
LB-GETSEL | Retrieves the selection state of an item in a multiple-selection list box control.
LB-GETSELCOUNT | Retrieves the total number of selected items in a multiple-selection list box control.
LB-GETSELITEMS | Fills a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box control.
LB-GETTEXT | Retrieves a string from a list box control.
LB-GETTEXTLEN | Retrieves the length of a string in a list box control.
LB-GETTOPINDEX | Retrieves the index of the first visible item in a list box control.
LB-INSERTSTRING | Inserts a string into a list box control.
LB-RESETCONTENT | Removes all items from a list box control.
LB-SELECTSTRING | Searches a list box control for an item that begins with the characters in a specified string.
LB-SELITEMRANGE | Selects one or more consecutive items in a multiple-selection list box control.
LB-SETCARETINDEX | Sets the focus rectangle to the item at the specified index in a multiple-selection list box control.
LB-SETCOLUMNWIDTH | Sets the width, in pixels, of all columns in a multiple-column list box control.
LB-SETCURSEL | Selects a string and scrolls it into view, if necessary, in a single-selection list box control.
LB-SETHORIZONTALEXTENT | Sets the width, in pixels, by which a list box control can be scrolled horizontally.
LB-SETITEMHEIGHT | Sets the height of items in a list box control.
LB-SETSEL | Selects a string in a multiple-selection list box control.
LB-SETTABSTOPS | Sets the tab-stop positions in a list box control.
LB-SETTOPINDEX | Ensures that a particular item in a list box is visible control.


LB-ADDSTRING

Object Manipulation Message: List Box

An application sends an LB-ADDSTRING message to add a string to a list box control. If this list box does not have the CBS-SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

Calling Sequence

CALL SENDMESSAGE USING WIN RETURN LB-H LB-ADDSTRING 0 NEW-ENTRY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index to the string in the list box. The return value is LB-ERR if an error occurs; the return value is LB-ERRSPACE if insufficient space is available to store the new string.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-ADDSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
0 | Not used. | Must be zero.
NEW-ENTRY | alphanumeric | Contains the string that is to be added.


LB-DELETESTRING

Object Manipulation Message: List Box

An application sends an LB-DELETESTRING message to delete a string in a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-DELETESTRING ENTRY-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a count of the strings remaining in the list. The return value is LB-ERR if the ENTRY-NUM parameter specifies an index greater than the number of items in the list.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-DELETESTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ENTRY-NUM | numeric | Specifies the zero-based index of the string to delete.


LB-DIR

Object Manipulation Message: List Box

An application sends an LB-DIR message to add a list of filenames to a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-DIR FILE-ATTRS FILESPEC.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the last filename added to the list. The return value is LB-ERR if an error occurs; the return value is LB-ERRSPACE if insufficient space is available to store the new strings.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-DIR | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
FILE-ATTRS | windows.cpy | Specifies the attributes of the files to be added to the list box. It can be one or more of the following values:
 | Value | Meaning
 | DDL-ARCHIVE | List includes archived files.
 | DDL-DIRECTORY | List includes subdirectories, which are enclosed in square brackets ([ ]).
 | DDL-DRIVES | List includes all drives that match the name specified by the FILE-SPEC parameter are included. If the DDL-DRIVES flag is set, the DDL-EXCLUSIVE flag is set automatically. Therefore, to create a directory listing that includes drives and files, the developer must send this message twice: once with the DDL-DRIVES flag set and once with the flags for the rest of the list.
 | DDL-EXCLUSIVE | List includes only files with the specified attributes. By default, read-write files are listed even if DDL-READWRITE is not specified.
 | DDL-HIDDEN | List includes hidden files.
 | DDL-READONLY | List includes read-only files.
 | DDL-READWRITE | List includes read-write files with no additional attributes. This is the default.
 | DDL-SYSTEM | List includes system files.
FILESPEC | alphanumeric | Pointer to a null-terminated string that specifies an absolute path, relative path, or filename. An absolute path can begin with a drive letter (for example, d:\) or a UNC name (for example, \\ machinename\ sharename). If the string specifies a filename or directory that has the attributes specified by the FILE-ATTRS parameter, the filename or directory is added to the list. If the file name or directory name contains wildcard characters (? or *), all files or directories that match the wildcard expression and have the attributes specified by the FILE-ATTRS parameter are added to the list displayed in the combo box.


LB-FINDSTRING

Object Manipulation Message: List Box

An application sends an LB-FINDSTRING message to search a list box control for an item that begins with the characters in a specified string.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-FINDSTRING
INDEX-START SEARCH-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the matching item, or it is LB-ERR if the search was unsuccessful.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-FINDSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | numeric | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START is -1, the entire list box is searched from the beginning.
SEARCH-TEXT | alphanumeric | A string that contains the prefix to search for. The search is not case-sensitive, so this string can contain any combination of uppercase and lowercase letters.


LB-FINDSTRINGEXACT

Object Manipulation Message: List Box

An application sends an LB-FINDSTRINGEXACT message to find the first list box control string that matches the string specified in the SEARCH-TEXT parameter.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-FINDSTRINGEXACT
INDEX-START SEARCH-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the matching item, or it is LB-ERR if the search was unsuccessful.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-FINDSTRINGEXACT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | windows.cpy | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START is -1, the entire list box is searched from the beginning.
SEARCH-TEXT | alphanumeric | The string to search for. This string can contain a complete filename, including the extension. The search is not case-sensitive, so the string can contain any combination of uppercase and lowercase letters.


LB-GETCARETINDEX

Object Manipulation Message: List Box

An application sends an LB-GETCARETINDEX message to determine the index of the item that has the focus rectangle in a multiple-selection list box control. The item may or may not be selected.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETCARETINDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the item that has the focus rectangle in a list box. If the list box is a single-selection list box, the return value is the index of the item that is selected, if any.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETCARETINDEX | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETCOUNT

Object Manipulation Message: List Box

An application sends an LB-GETCOUNT message to retrieve the number of items in a list box control.

The returned count is one greater than the index value of the last item (the index is zero-based).

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETCOUNT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of items in the list box, or it is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETCOUNT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETCURSEL

Object Manipulation Message: List Box

An application sends an LB-GETCURSEL message to retrieve the index of the currently selected item, if any, in a single-selection list box control.

To retrieve the indexes of the selected items in a multiple-selection list box, use the LB-GETSELITEMS message. To determine whether the item that has the focus rectangle in a multiple-selection list box is selected, use the LB-GETSEL message.

The LB-GETCURSEL message cannot be sent to a multiple-selection list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETCURSEL.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the currently selected item. It is LB-ERR if no item is currently selected.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETCURSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETHORIZONTALEXTENT

Object Manipulation Message: List Box

An application sends the LB-GETHORIZONTALEXTENT message to retrieve from a list box control the width, in pixels, by which the list box can be scrolled horizontally if the list box has a horizontal scroll bar.

To respond to the LB-GETHORIZONTALEXTENT message, the list box must have been defined with the WS-HSCROLL style.

This message is not useful for multicolumn list box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETHORIZONTALEXTENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the scrollable width of the list box, in pixels.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETHORIZONTALEXTENT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETITEMHEIGHT

Object Manipulation Message: List Box

An application sends an LB-GETITEMHEIGHT message to determine the height of items in a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETITEMHEIGHT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the height, in pixels, of the items in the list box. The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETITEMHEIGHT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETITEMRECT

Object Manipulation Message: List Box

An application sends an LB-GETITEMRECT message to retrieve the dimensions of the rectangle that bounds an item as it is currently displayed in the list box window.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETITEMRECT
ITEM-INDEX RECT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETITEMRECT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-INDEX | numeric | Specifies the zero-based index of the item.
RECT | windows.cpy | Specifies a pointer to a RECT structure that receives the client coordinates for the item in the list box. The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.


LB-GETSEL

Object Manipulation Message: List Box

An application sends an LB-GETSEL message to retrieve the selection state of an item in a multiple-selection list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETSEL ITEM-INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a positive number if an item is selected; otherwise, it is 0. The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-INDEX | numeric | Specifies the zero-based index of the item.


LB-GETSELCOUNT

Object Manipulation Message: List Box

An application sends an LB-GETSELCOUNT message to retrieve the total number of selected items in a multiple-selection list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETSELCOUNT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the count of selected items in a list box. The return value is LB-ERR if the list box is a single-selection list box.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETSELCOUNT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-GETSELITEMS

Object Manipulation Message: List Box

An application sends an LB-GETSELITEMS message to fill a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box control.

The return value is the actual number of items placed in the buffer. The return value is LB-ERR if the list box is a single-selection list box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETSELITEMS
ITEM-COUNT ITEM-ARRAY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the actual number of items placed in the buffer. The return value is LB-ERR if the list box is a single-selection list box.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETSELITEMS | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-COUNT | numeric | Specifies the maximum number of selected items whose item numbers are to be placed in the buffer.
ITEM-ARRAY | PIC 9(4) COMP-4 occurs n times | Specifies an array large enough for the number of integers specified by the ITEM-COUNT parameter.


LB-GETTEXT

Object Manipulation Message: List Box

An application sends an LB-GETTEXT message to retrieve a string from a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETTEXT
ITEM-INDEX TEXT-AREA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length of the string, in bytes. The return value is LB-ERR if the ITEM-INDEX parameter does not specify a valid index.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-INDEX | numeric | Specifies the zero-based index of the string to retrieve.
TEXT-AREA | alphanumeric | A buffer that receives the string;. The buffer must have sufficient space for the string. An LB-GETTEXTLEN message can be sent before the LB-GETTEXT message to retrieve the length, in bytes, of the string.


LB-GETTEXTLEN

Object Manipulation Message: List Box

An application sends an LB-GETTEXTLEN message to retrieve the length of a string in a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-GETTEXTLEN ITEM-INDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the length of the string, in bytes. The return value is LB-ERR if the ITEM-INDEX parameter does not specify a valid index.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETTEXTLEN | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-INDEX | windows.cpy | Specifies the zero-based index of the string.


LB-GETTOPINDEX

Object Manipulation Message: List Box

An application sends an LB-GETTOPINDEX message to retrieve the index of the first visible item in a list box control. Initially, the item with index 0 is at the top of the list box, but if the list box is scrolled, another item may be at the top.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H
LB-GETTOPINDEX.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the zero-based index of the first visible item in a list box.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-GETTOPINDEX | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-INSERTSTRING

Object Manipulation Message: List Box

An application sends an LB-INSERTSTRING message to insert a string into a list box control. Unlike the LB-ADDSTRING message, the LB-INSERTSTRING message does not cause a list with the LBS-SORT style to be sorted.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-INSERTSTRING
INS-POS NEW-ENTRY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the position at which the string was inserted. The return value is LB-ERR if an error occurs. The return value is LB-ERRSPACE if insufficient space is available to store the new string.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-INSERTSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INS-POS | numeric | Specifies the zero-based index of the position at which to insert the string. If the value of this parameter is -1, the string is added to the end of the list.
NEW-ENTRY | alphanumeric | The string that is to be inserted.


LB-RESETCONTENT

Object Manipulation Message: List Box

An application sends an LB-RESETCONTENT message to remove all items from a list box control.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-RESETCONTENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-RESETCONTENT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


LB-SELECTSTRING

Object Manipulation Message: List Box

An application sends an LB-SELECTSTRING message to search a list box control for an item that begins with the characters in a specified string. If a matching item is found, the item is selected.

The list box is scrolled, if necessary, to bring the selected item into view.

An item is selected only if its initial characters (from the starting point) match the characters in the string specified by the SELECT-TEXT parameter.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SELECTSTRING
INDEX-START SELECT-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the index of the selected item if the search was successful. The return value is LB-ERR if the search was unsuccessful and the current selection is not changed.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SELECTSTRING | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-START | numeric | Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the INDEX-START parameter. If INDEX-START is -1, the entire list box is searched from the beginning.
SELECT-TEXT | alphanumeric | The string that contains the prefix to search for. The search is not case-sensitive, so this string can contain any combination of uppercase and lowercase letters.


LB-SELITEMRANGE

Object Manipulation Message: List Box

An application sends an LB-SELITEMRANGE message to select one or more consecutive items in a multiple-selection list box control.

This message should be used only with multiple-selection list box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SELITEMRANGE
SEL-FLAG FIRST-ITEM LAST-ITEM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SELITEMRANGE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
SEL-FLAG | numeric | Specifies how to set the selection. If the SEL-FLAG parameter is nonzero, the string is selected and highlighted; if SEL-FLAG is zero, the highlight is removed and the string is no longer selected.
FIRST-ITEM | numeric | Specifies the zero-based index of the first item to set.
LAST-ITEM | numeric | Specifies the zero-based index of the last item to set.


LB-SETCARETINDEX

Object Manipulation Message: List Box

An application sends an LB-SETCARETINDEX message to set the focus rectangle to the item at the specified index in a multiple-selection list box control. If the item is not visible, it is scrolled into view.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETCARETINDEX
INDEX-NUM SCROLL-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETCARETINDEX | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the item to receive the focus rectangle in the list box.
SCROLL-FLAG | numeric | If this value is zero, the item is scrolled until it is fully visible. If this value is nonzero, the item is scrolled until it is at least partially visible.


LB-SETCOLUMNWIDTH

Object Manipulation Message: List Box

An application sends an LB-SETCOLUMNWIDTH message to a multiple-column list box control (created with the LBS-MULTICOLUMN style) to set the width, in pixels, of all columns in the list box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETCOLUMNWIDTH COL-WIDTH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETCOLUMNWIDTH | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
COL-WIDTH | numeric | Specifies the width, in pixels, of all columns.


LB-SETCURSEL

Object Manipulation Message: List Box

An application sends an LB-SETCURSEL message to select a string and scroll it into view, if necessary, in a list box control. When the new string is selected, the list box removes the highlight from the previously selected string.

This message should be used only with single-selection list box controls. It cannot be used to set or remove a selection in a multiple-selection list box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETCURSEL INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs. The return value will be LB-ERR even though no error has occurred if the INDEX-NUM parameter is -1.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETCURSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the string that is selected. If the INDEX-NUM parameter is -1, the list box is set to have no selection.


LB-SETHORIZONTALEXTENT

Object Manipulation Message: List Box

An application sends the LB-SETHORIZONTALEXTENT message to set the width, in pixels, by which a list box control can be scrolled horizontally. If the size of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the size of the list box is equal to or greater than this value, the horizontal scroll bar is hidden.

To respond to the LB-SETHORIZONTALEXTENT message, the list box must have been defined with the WS-HSCROLL style.

By default, the horizontal extent of a list box is zero. Windows does not display the scroll bar unless the horizontal extent is set to a value greater than the width, in pixels, of the client area of the list box.

This message is not useful for multicolumn list box controls. Multicolumn list boxes should instead use the LB-SETCOLUMNWIDTH message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETHORIZONTALEXTENT
SCROLL-SIZE 0.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETHORIZONTALEXTENT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
SCROLL-SIZE | numeric | Specifies the number of pixels by which the list box can be scrolled horizontally.


LB-SETITEMHEIGHT

Object Manipulation Message: List Box

An application sends an LB-SETITEMHEIGHT message to set the height of items in a list box control. If the list box has the LBS-OWNERDRAWVARIABLE style, this message sets the height of the item specified by the ITEM-INDEX parameter. Otherwise, this message sets the height of all items in the list box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETITEMHEIGHT
ITEM-INDEX ITEM-HEIGHT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if the index or height is invalid.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETITEMHEIGHT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
ITEM-INDEX | numeric | Specifies the zero-based index of the item in the list box. Use this parameter only if the list box has the LBS-OWNERDRAWVARIABLE style. Otherwise, set it to zero.
ITEM-HEIGHT | numeric | Specifies the height, in pixels, of the item.


LB-SETSEL

Object Manipulation Message: List Box

An application sends an LB-SETSEL message to select a string in a multiple-selection list box control.

This message should be used only with multiple-selection list box controls.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETSEL
SELECT-FLAG INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETSEL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
SELECT-FLAG | numeric | Specifies how to set the selection. If the SELECT-FLAG parameter is WIN-TRUE, the string is selected and highlighted; if the value of SELECT-FLAG is WIN-FALSE, the highlight is removed and the string is no longer selected.
INDEX-NUM | numeric | Specifies the zero-based index of the string to set. If the INDEX-NUM parameter is -1, the selection is added to or removed from all strings, depending on the value of SELECT-NUM.


LB-SETTABSTOPS

Object Manipulation Message: List Box

An application sends an LB-SETTABSTOPS message to set the tab-stop positions in a list box control.

To respond to the LB-SETTABSTOPS message, the list box must have been created with the LBS-USETABSTOPS style.

If the TAB-COUNT parameter is zero and the TAB-ARRAY parameter is 0, the default tab stop is two dialog box units.

If TAB-COUNTS is 1, the list box will have tab stops separated by the distance specified by TAB-ARRAY.

If TAB-ARRAY contains more than a single value, a tab stop will be set for each value in TAB-ARRAY, up to the number specified by TAB-COUNT.

A dialog box unit is a horizontal or vertical distance. One horizontal dialog box unit is equal to one-fourth of the current dialog box base width unit. The dialog box base units are computed based on the height and width of the current system font. The GETDIALOGBASEUNITS function returns the current dialog box base units, in pixels.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETTABSTOPS
TAB-COUNT TAB-ARRAY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if all the tabs were set; otherwise, the return value is zero.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETTABSTOPS | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
TAB-COUNT | numeric | Specifies the number of tab stops in the list box.
TAB-ARRAY | PIC 9(4) COMP-4 occurs n times | An array of integers containing the tab stops, in dialog box units. The tab stops must be sorted in increasing order; back tabs are not allowed.


LB-SETTOPINDEX

Object Manipulation Message: List Box

An application sends an LB-SETTOPINDEX message to ensure that a particular item in a list box control is visible.

The system scrolls the list box so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN LB-H LB-SETTOPINDEX INDEX-NUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERR if an error occurs.
LB-H | PIC 9(10) BINARY(8) | The handle of the list box to which the message will be sent.
LB-SETTOPINDEX | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
INDEX-NUM | numeric | Specifies the zero-based index of the item in the list box.


Progress Bar Messages

See Also

The following table summarizes the progress bar messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
PBM-DELTAPOS | Advances the current position of a progress bar control by a specified increment and redraws the bar to reflect the new position.
PBM-SETPOS | Sets the current position for a progress bar control and redraws the bar to reflect the new position.
PBM-SETRANGE32 | Sets the minimum and maximum values for a progress bar control and redraws the bar to reflect the new range.
PBM-SETSTEP | Specifies the step increment for a progress bar control. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM-STEPIT message. By default, the step increment is set to 10.
PBM-STEPIT | Advances the current position for a progress bar control by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM-SETSTEP message.


PBM-DELTAPOS

Object Manipulation Message: Progress Bar

An application sends a PBM-DELTAPOS message in order to advance the current position of a progress bar control by a specified increment and redraw the bar to reflect the new position.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H PBM-DELTAPOS INCREMENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | Returns the previous position of the progress bar.
WND-H | PIC 9(10) BINARY(8) | The handle of the progress bar to which the message will be sent.
PBM-DELTAPOS | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
Increment | windows.cpy | Specifies the value to add to the current position of the progress bar.


PBM-SETPOS

Object Manipulation Message: Progress Bar

An application sends a PBM-SETPOS message in order to set the current position of a progress bar control and redraw the bar to reflect the new position.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H PBM-SETPOS NEWPOS.

Parameter | Declaration | Description
WIN-RETURN | numeric | Returns the previous position of the progress bar.
WND-H | PIC 9(10) BINARY(8) | The handle of the progress bar to which the message will be sent.
PBM-SETPOS | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
NEWPOS | windows.cpy | Specifies the value of the new position of the progress bar.


PBM-SETRANGE32

Object Manipulation Message: Progress Bar

An application sends a PBM-SETRANGE32 message in order to set the minimum and maximum values for a progress bar's position and redraw the progress bar control to reflect the new range.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H PBM-SETRANGE32
MAXIMUM MINIMUM.

Parameter | Declaration | Description
WIN-RETURN | numeric | Returns the previous position of the progress bar.
WND-H | PIC 9(10) BINARY(8) | The handle of the progress bar to which the message will be sent.
PBM-SETRANGE32 | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
MAXIMUM | windows.cpy | Specifies the maximum value of the progress bar position.
MINIMUM | windows.cpy | Specifies the minimum value of the progress bar position.


PBM-SETSTEP

Object Manipulation Message: Progress Bar

An application sends a PBM-SETSTEP message in order to specify the step increment for a progress bar control. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM-STEPIT message. By default, the step increment is set to 10.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H PBM-SETSTEP INCREMENT.

Parameter | Declaration | Description
WIN-RETURN | numeric | Returns the previous position of the progress bar.
WND-H | PIC 9(10) BINARY(8) | The handle of the progress bar to which the message will be sent.
PBM-SETSTEP | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
Increment | windows.cpy | Specifies the step increment. The default value is 10.


PBM-STEPIT

Object Manipulation Message: Progress Bar

An application sends a PBM-STEPIT message in order to advance the current position for a progress bar control by the step increment and redraw the progress bar to reflect the new position. An application sets the step increment by sending the PBM-SETSTEP message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H PBM-STEPIT.

Parameter | Declaration | Description
WIN-RETURN | numeric | Returns the previous position of the progress bar.
WND-H | PIC 9(10) BINARY(8) | The handle of the progress bar to which the message will be sent.
PBM-STEPIT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


Send Messages

See Also

The following table summarizes the Send messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
WM-CLEAR | Deletes the current selection, if any, in the edit box portion of a combo box control or in the edit box control.
WM-COPY | Copies the current selection to the Clipboard in CF-TEXT format.
WM-CUT | Deletes the current selection, if any, in the edit box portion of a combo box control or in the edit box control, and copies the deleted text to the Clipboard in CF-TEXT format.
WM-FONTCHANGE | Sent to all top-level forms in the system after changing the pool of font forms.
WM-GETFONT | Sent to a control to retrieve the font with which the control is currently drawing its text.
WM-GETICON | Retrieves a handle to a new large or small icon associated with a form.
WM-GETTEXT | Copies the text that corresponds to a window into a buffer provided by the caller.
WM-GETTEXTLENGTH | Sends a WM-GETTEXTLENGTH message to determine the length, in bytes, of the text associated with a window.
WM-NEXTDLGCTL | Sends the WM-NEXTDLGCTL message to a form to set the focus to a different control on the form.
WM-PASTE | Inserts the data from the Clipboard into the edit box portion of the combo box control or into the edit box control at the current cursor position.
WM-SETFONT | Sent to a control to specify the font that a control is to use when drawing text.
WM-SETICON | Associates a new large or small icon with a form.
WM-SETREDRAW | Allows changes in a control to be redrawn or prevents changes in that control from being redrawn.
WM-SETTEXT | Sets the text of a window.
WM-UNDO | Undoes the last operation.


WM-CLEAR

Object Manipulation Message: Send

An application sends a WM-CLEAR message to an edit box control or combo box control to delete (clear) the current selection, if any, in the edit box or edit box portion of the control.

To delete the current selection and place the deleted contents into the Clipboard, use the WM-CUT message.

To undo the deletion performed by the WM-CLEAR message, send the edit box an EM-UNDO message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CTRL-H WM-CLEAR.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if this message is sent to an edit box or a combo box; otherwise, the return value is zero.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-CLEAR | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-COPY

Object Manipulation Message: Send

An application sends a WM-COPY message to an edit box or combo box to copy the current selection to the Clipboard in CF-TEXT format.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CTRL-H WM-COPY.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if this message is sent to an edit box or a combo box.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-COPY | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-CUT

Object Manipulation Message: Send

An application sends a WM-CUT message to an edit box control or combo box control to delete (cut) the current selection, if any, in the edit box or edit box portion of the control, and then copy the deleted text to the Clipboard in CF-TEXT format.

To delete the current selection without placing the deleted text into the Clipboard, use the WM-CLEAR message.

To undo the deletion performed by the WM-CUT message, send the edit box an EM-UNDO message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CTRL-H WM-CUT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if this message is sent to an edit box or a combo box; otherwise, the return value is zero.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-CUT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-FONTCHANGE

Object Manipulation Message: Send

An application sends the WM-FONTCHANGE message to all top-level windows in the system after changing the pool of font resources.

To send the WM-FONTCHANGE message to all top-level windows, an application can call the SENDMESSAGE function with the WND-H parameter set to HWND-BROADCAST.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN HWND-BROADCAST WM-FONTCHANGE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the function is successful. Otherwise, it is zero.
HWND-BROADCAST | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
WM-FONTCHANGE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-GETFONT

Object Manipulation Message: Send

An application sends a WM-GETFONT message to a control to retrieve the font with which the control is currently drawing its text.

Calling Sequence

CALL SENDMESSAGE USING FONT-H CTRL-H WM-GETFONT.

Parameter | Declaration | Description
FONT-H | PIC 9(10) BINARY(8) | The return value is the handle of the font used by the control, or it is zero if the control is using the system font.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-GETFONT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-GETICON

Object Manipulation Message: Send

An application sends the WM-GETICON message to retrieve a handle to a new large or small icon associated with a form.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN FORM-H WM-GETICON
ICON-TYPE ICON-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
FORM-H | PIC 9(10) BINARY(8) | The handle of the form for which to set the icon.
ICON-TYPE | Possible values are declared as 78-level descriptions in windows.cpy. | The type of icon to be used.
ICON-H | PIC 9(10) BINARY(8) | The handle of the icon to use for the form.


WM-GETTEXT

Object Manipulation Message: Send

An application sends a WM-GETTEXT message to copy the text that corresponds to a window into a buffer provided by the caller.

For an edit box, the text to be copied is the contents of the edit box. For a combo box, the text is the contents of the edit box (or static text box) portions of the combo box. For a button control, the text is the button name. For other windows, the text is the window title. To copy the text of an item in a list box, an application can use the LB-GETTEXT message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H WM-GETTEXT
TEXT-MAX TEXT-AREA.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is the number of bytes copied. It is CB-ERR if the message is sent to a combo box that has no edit box.
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control to which the message will be sent.
WM-GETTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
TEXT-MAX | windows.cpy | Specifies the maximum number of bytes to be copied.
TEXT-AREA | windows.cpy | The buffer that is to receive the text.


WM-GETTEXTLENGTH

Object Manipulation Message: Send

An application sends a WM-GETTEXTLENGTH message to determine the length, in bytes, of the text associated with a window. The length does not include the terminating null character.

For an edit box, the text to be copied is the contents of the edit box. For a combo box, the text is the contents of the edit box (or static text box) portions of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To determine the length of an item in a list box, an application can use the LB-GETTEXTLEN message.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H WM-GETTEXTLENGTH.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is a word specifying the length, in bytes, of the text.
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control to which the message will be sent.
WM-GETTEXTLENGTH | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-NEXTDLGCTL

Object Manipulation Message: Send

An application sends the WM-NEXTDLGCTL message to a dialog box procedure to set the focus to a different control in a dialog box.

The effect of this message differs from that of the SETFOCUS function because WM-NEXTDLGCTL modifies the border around the default button.

Do not use the SENDMESSAGE function to send a WM-NEXTDLGCTL message if your application will concurrently process other messages that set the control focus.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H WM-NEXTDLGCTL
CTL-FOCUS HANDLE-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window or control to which the message will be sent.
WM-NEXTDLGCTL | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
CTL-FOCUS | windows.cpy | If the HANDLE-FLAG parameter is nonzero, the CTL-FOCUS parameter is the handle of the control that receives the focus. If HANDLE-FLAG is zero, CTL-FOCUS is a flag that indicates whether the next or previous control with the WS-TABSTOP style receives the focus. If CTL-FOCUS is zero, the next control receives the focus; otherwise, the previous control with the WS-TABSTOP style receives the focus.
HANDLE-FLAG | numeric | Indicates how Windows uses the CTL-FOCUS parameter. If HANDLE-FLAG is nonzero, CTL-FOCUS is a handle associated with the control that receives the focus; otherwise, CTL-FOCUS is a flag that indicates whether the next or previous control with the WS-TABSTOP style receives the focus.


WM-PASTE

Object Manipulation Message: Send

An application sends the WM-PASTE message to an edit box or combo box to insert the data from the Clipboard into the edit box at the current cursor position. Data is inserted only if the Clipboard contains data in the CF-TEXT format.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CTRL-H WM-PASTE.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if this message is sent to an edit box or a combo box; otherwise, the return value is zero.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-PASTE | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


WM-SETFONT

Object Manipulation Message: Send

An application sends the WM-SETFONT message to specify the font that a control is to use when drawing text.

The WM-SETFONT message applies to all controls, not just those in dialog boxes.

The application should call the DELETEOBJECT function to delete the font when it is no longer needed; for example, after the control is destroyed.

The size of the control is not changed as a result of receiving this message. To prevent Windows from clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before changing the font.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN CTRL-H WM-SETFONT
FONT-H REDRAW-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value nonzero if the function is successful. Otherwise, it is zero.
CTRL-H | PIC 9(10) BINARY(8) | The handle of the control to which the message will be sent.
WM-SETFONT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
FONT-H | PIC 9(10) BINARY(8) | Specifies the handle of the font. If the value of this parameter is zero, the control will use the default system font to draw text.
REDRAW-FLAG | numeric | Specifies whether the control should be redrawn immediately upon setting the font. Setting the REDRAW-FLAG parameter to WIN-TRUE causes the control to redraw itself.


WM-SETICON

Object Manipulation Message: Send

An application sends the WM-SETICON message to associate a new large or small icon with a form.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN FORM-H WM-SETICON
ICON-TYPE ICON-H.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
FORM-H | PIC 9(10) BINARY(8) | The handle of the form for which to set the icon.
ICON-TYPE | Possible values are declared as 78-level descriptions in windows.cpy. | The type of icon to be used.
ICON-H | PIC 9(10) BINARY(8) | The handle of the icon to use for the form.


WM-SETREDRAW

Object Manipulation Message: Send

An application sends a WM-SETREDRAW message to a window to allow changes in that window to be redrawn or to prevent changes in that window from being redrawn.

This message sets or clears the redraw flag. If the redraw flag is cleared, the contents of the specified window will not be updated after each change, and the window will not be repainted until the redraw flag is set. For example, an application that needs to add several items to a list box can clear the redraw flag, add the items, and then set the redraw flag.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H WM-SETREDRAW REDRAW-FLAG.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is always zero.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
WM-SETREDRAW | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
REDRAW-FLAG | numeric | Specifies whether the control should be redrawn. Setting the REDRAW-FLAG parameter to WIN-TRUE causes the control to redraw itself. Setting the value to WIN-FALSE prevents the control from redrawing itself.


WM-SETTEXT

Object Manipulation Message: Send

An application sends a WM-SETTEXT message to set the text of a window.

For an edit box, the text to be set is the contents of the edit box. For a combo box, the text is the contents of the edit box (or static text box) portions of the combo box. For a button, the text is the button name. For other windows, the text is the window title.

This message does not change the current selection in the list box portion of a combo box. An application should use the CB-SELECTSTRING message to select the item in the list box that matches the text in the edit box.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN WND-H WM-SETTEXT 0 NEW-TEXT.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is LB-ERRSPACE (for a list box) or CB-ERRSPACE (for a combo box) if insufficient space is available to set the text in the edit box. It is CB-ERR if this message is sent to a combo box without an edit box.
WND-H | PIC 9(10) BINARY(8) | The handle of the window to which the message will be sent.
WM-SETTEXT | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.
0 | Not used. | Must be zero.
NEW-TEXT | alphanumeric | A string that is the window text.


WM-UNDO

Object Manipulation Message: Send

An application sends the WM-UNDO message to an edit box to undo the last operation. When this message is sent to an edit box, the previously deleted text is restored or the previously added text is deleted.

Note Compare this message to EM-UNDO, which undoes other edit box operations.

Calling Sequence

CALL SENDMESSAGE USING WIN-RETURN ED-H WM-UNDO.

Parameter | Declaration | Description
WIN-RETURN | numeric | The return value is nonzero if the operation is successful, or it is zero if an error occurs.
ED-H | PIC 9(10) BINARY(8) | The handle of the edit box to which the message will be sent.
WM-UNDO | Possible values are declared as 78-level descriptions in windows.cpy. | The ID of the message to be sent.


Event-Triggering Messages

See Also

Some messages are used only to inform application programs of actions that have occurred on forms and controls (objects). These messages are called notification messages. Notification messages are never sent by application programs to objects; rather, they are sent only from objects to application programs. WOW Extensions automatically translates these messages into events. The developer enters event-handling code for processing these events in the Event-Handling Code window when designing the interface.

To view descriptions of the messages that trigger events, click one of the following topics.

· Button Notification Messages

· Combo Box Notification Messages

· Edit Box Notification Messages

· List Box Notification Messages

· Window Notification Messages


Button Notification Messages

See Also

The following table summarizes the button notification messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
BN-CLICKED | Sent when the user clicks a button.
BN-DOUBLECLICKED | Sent when the user double-clicks a button.


BN-CLICKED

Event-Triggering Message: Button Notification

The BN-CLICKED notification message is sent to the parent window when the user clicks a button contained in the window. Unlike the other button notification messages, this message is intended for applications written for any version of Windows.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as BN-CLICKED.
WIN-LPARAM | windows.cpy | Contains a handle that identifies the button control.
WIN-WPARAM-L | windows.cpy | Specifies the control identifier of the button.
WIN-WPARAM-H | windows.cpy | Contains the BN-CLICKED notification code.


BN-DOUBLECLICKED

Event-Triggering Message: Button Notification

The BN-DOUBLECLICKED notification message is sent when the user double-clicks a button. This notification is provided for compatibility with applications written prior to Windows version 3.0.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as BN-DOUBLECLICKED.
WIN-LPARAM | windows.cpy | Contains a handle that identifies the button control.
WIN-WPARAM-L | windows.cpy | Specifies the control identifier of the button.
WIN-WPARAM-H | windows.cpy | Contains the BN-DOUBLECLICKED notification code.


Combo Box Notification Messages

See Also

The following table summarizes the combo box notification messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
CBN-DBLCLK | Sent when the user double-clicks a string in the list box portion of a combo box.
CBN-DROPDOWN | Sent when the list box portion of a combo box is about to be dropped down (that is, made visible).
CBN-EDITCHANGE | Sent after the user has taken an action that may have altered the text in the edit box portion of a combo box.
CBN-ERRSPACE | Sent when a combo box cannot allocate enough memory to meet a specific request.
CBN-KILLFOCUS | Sent when a combo box loses the input focus.
CBN-SELCHANGE | Sent when the selection in the list box portion of a combo box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys.
CBN-SETFOCUS | Sent when a combo box receives the input focus.


CBN-DBLCLK

Event-Triggering Message: Combo Box Notification

The CBN-DBLCLK notification message is sent when the user double-clicks a string in the list box of a combo box. The control’s parent window receives this notification message through a WM-COMMAND message.

This notification message can occur only for a combo box with the CBS-SIMPLE style. For a combo box with the CBS-DROPDOWN or CBS-DROPDOWNLIST style, a double-click cannot occur because a single-click hides the list box.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-DBLCLK notification message.


CBN-DROPDOWN

Event-Triggering Message: Combo Box Notification

The CBN-DROPDOWN notification message is sent when the list box of a combo box is about to be dropped down (made visible). The parent window of the combo box receives this notification message through a WM-COMMAND message.

This notification message can occur only for a combo box with the CBS-DROPDOWN or CBS-DROPDOWNLIST style.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-DROPDOWN notification message.


CBN-EDITCHANGE

Event-Triggering Message: Combo Box Notification

The CBN-EDITCHANGE notification message is sent after the user has taken an action that may have altered the text in the edit box control portion of a combo box. Unlike the CBN-EDITUPDATE notification message, this notification message is sent after Windows updates the screen. The parent window of the combo box receives this notification message through a WM-COMMAND message.

This message does not occur if the combo box has the CBS-DROPDOWNLIST style.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-EDITCHANGE notification message.


CBN-ERRSPACE

Event-Triggering Message: Combo Box Notification

The CBN-ERRSPACE notification message is sent when a combo box cannot allocate enough memory to meet a specific request. The parent window of the combo box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-ERRSPACE notification message.


CBN-KILLFOCUS

Event-Triggering Message: Combo Box Notification

The CBN-KILLFOCUS notification message is sent when a combo box loses the input focus. The parent window of the combo box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-KILLFOCUS notification message.


CBN-SELCHANGE

Event-Triggering Message: Combo Box Notification

The CBN-SELCHANGE notification message is sent when the selection in the list box of a combo box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys. The parent window of the combo box receives this code through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-SELCHANGE notification message.


CBN-SETFOCUS

Event-Triggering Message: Combo Box Notification

The CBN-SETFOCUS notification message is sent when a combo box receives the input focus. The parent window of the combo box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-SETFOCUS notification message.


Edit Box Notification Messages

See Also

The following table summarizes the edit box notification messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
EN-CHANGE | Sent when the user has taken an action that may have altered text in an edit box control.
EN-ERRSPACE | Sent when an edit box control cannot allocate enough memory to meet a specific request.
EN-HSCROLL | Sent when the user clicks an edit box control’s horizontal scroll bar.
EN-KILLFOCUS | Sent when an edit box control loses the input focus.
EN-MAXTEXT | Sent when the current insertion has exceeded the specified number of characters for the edit box control.
EN-SETFOCUS | Sent when an edit box control receives the input focus.
EN-VSCROLL | Sent when the user clicks an edit box control’s vertical scroll bar.


EN-CHANGE

Event-Triggering Message: Edit Box Notification

The EN-CHANGE notification message is sent when the user has taken an action that may have altered text in an edit box control. Unlike the EN-UPDATE notification message, this notification message is sent after Windows updates the display. The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-CHANGE notification message.


EN-ERRSPACE

Event-Triggering Message: Edit Box Notification

The EN-ERRSPACE notification message is sent when an edit box control cannot allocate enough memory to meet a specific request. The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-ERRSPACE notification message in the high-order word.


EN-HSCROLL

Event-Triggering Message: Edit Box Notification

The EN-HSCROLL notification message is sent when the user clicks an edit box control’s horizontal scroll bar. The control’s parent window receives this notification message through a WM-COMMAND message. The parent window is notified before the screen is updated.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-HSCROLL notification message in the high-order word.


EN-KILLFOCUS

Event-Triggering Message: Edit Box Notification

The EN-KILLFOCUS notification message is sent when an edit box control loses the input focus. The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-KILLFOCUS notification message in the high-order word.


EN-MAXTEXT

Event-Triggering Message: Edit Box Notification

The EN-MAXTEXT notification message is sent when the current insertion has exceeded the specified number of characters for the edit box control. The insertion has been truncated.

This message is also sent when an edit box control does not have the ES-AUTOHSCROLL style and the number of characters to be inserted would exceed the width of the edit box control.

This message is also sent when an edit box control does not have the ES-AUTOHSCROLL style and the total number of lines resulting from a text insertion would exceed the height of the edit box control.

The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-MAXTEXT notification message in the high-order word.


EN-SETFOCUS

Event-Triggering Message: Edit Box Notification

The EN-SETFOCUS notification message is sent when an edit box control receives the input focus. The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-SETFOCUS notification message in the high-order word.


EN-VSCROLL

Event-Triggering Message: Edit Box Notification

The EN-VSCROLL notification message is sent when the user clicks an edit box control’s vertical scroll bar. The control’s parent window receives this notification message through a WM-COMMAND message. The parent window is notified before the screen is updated.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-VSCROLL notification message in the high-order word.


List Box Notification Messages

See Also

The following table summarizes the list box notification messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
LBN-DBLCLK | Sent when the user double-clicks a string in a list box.
LBN-KILLFOCUS | Sent when a list box loses the input focus.
LBN-SELCHANGE | Sent when the selection in a list box changes.
LBN-SETFOCUS | Sent when a list box receives the input focus.


LBN-DBLCLK

Event-Triggering Message: List Box Notification

The LBN-DBLCLK notification message is sent when the user double-clicks a string in a list box. The parent window of the list box receives this notification message through a WM-COMMAND message.

Only a list box that has LBS-NOTIFY style will send this notification message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the LBN-DBLCLK notification message.


LBN-KILLFOCUS

Event-Triggering Message: List Box Notification

The LBN-KILLFOCUS notification message is sent when a list box loses the input focus. The parent window of the list box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the LBN-KILLFOCUS notification message.


LBN-SELCHANGE

Event-Triggering Message: List Box Notification

The LBN-SELCHANGE notification message is sent when the selection in a list box is about to change. The parent window of the list box receives this notification message through a WM-COMMAND message.

This notification is not sent if the selection is changed by the LB-SETCURSEL message.

This notification applies only to a list box that has the LBS-NOTIFY style.

The LBN-SELCHANGE notification is sent for a multiple-selection lists box whenever the user presses an arrow key, even if the selection does not change.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the LBN-SELCHANGE notification message.


LBN-SETFOCUS

Event-Triggering Message: List Box Notification

The LBN-SETFOCUS notification message is sent when a list box receives the input focus. The parent window of the list box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the LBN-SETFOCUS notification message.


Window Notification Messages

See Also

The following table summarizes the window notification messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
WM-ACTIVATE | Sent when a form is being activated or deactivated.
WM-CHAR | Sent when a WM-KEYUP message and a WM-KEYDOWN message are translated.
WM-CLOSE | Sent as a signal that a form or an application should terminate.
WM-COMMAND | Sent to a form when the user selects an item from a menu, when a control sends a notification message to its parent, or when an accelerator keystroke is translated.
WM-CREATE | Sent when an application requests that a form be created.
WM-ENABLE | Sent when an application changes the enabled state of a form.
WM-HSCROLL | Sent to a form when the user clicks the form’s horizontal scroll bar.
WM-KEYDOWN | Sent when a non-system key is pressed.
WM-KEYUP | Sent when a non-system key is released.
WM-KILLFOCUS | Sent immediately before a form loses the input focus.
WM-LBUTTONDBLCLK | Sent when the user double-clicks the left mouse button.
WM-LBUTTONDOWN | Sent when the user presses the left mouse button.
WM-LBUTTONUP | Sent when the user releases the left mouse button.
WM-MBUTTONDOWN | Sent when the user presses the middle mouse button.
WM-MBUTTONUP | Sent when the user releases the middle mouse button.
WM-PAINT | Sent when the window needs to repaint itself.
WM-RBUTTONDOWN | Sent when the user presses the right mouse button.
WM-RBUTTONUP | Sent when the user releases the right mouse button.
WM-SETFOCUS | Sent after a form gains the input focus.
WM-SHOWWINDOW | Sent to a form when it is about to be hidden or shown.
WM-SIZE | Sent to a form after its size has changed.
WM-TIMER | Sent each interval specified in the SETTIMER function used to install a timer.
WM-VSCROLL | Sent to a form when the user clicks the form’s vertical scroll bar.


WM-ACTIVATE

Event-Triggering Message: Window Notification

The WM-ACTIVATE message is sent when a window is being activated or deactivated. This message is sent first to the window procedure of the main window being deactivated and then to the window procedure of the main window being activated.

If the window is activated with a mouse click, it also receives a WM-MOUSEACTIVATE message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-ACTIVATE.
WIN-LPARAM | windows.cpy | Identifies the handle of the window being activated or deactivated. This handle can be NULL.
WIN-WPARAM-L | windows.cpy | Specifies whether the window is being activated or deactivated. It can be one of the following values:
 | Value | Meaning
 | WA-ACTIVE | The window is being activated through some method other than a mouse click (for example, by use of the keyboard interface to select the window).
 | WA-CLICKACTIVE | The window is being activated by a mouse click.
 | WA-INACTIVE | The window is being deactivated.
WIN-WPARAM-H | windows.cpy | Specifies the minimized state of the window being activated or deactivated. A nonzero value indicates the window is minimized.


WM-CHAR

Event-Triggering Message: Window Notification

The WM-CHAR message is sent when a WM-KEYUP message and a WM-KEYDOWN message are translated. The WM-CHAR message contains the value of the key being pressed or released.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-CHAR.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code value of the key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-CLOSE

Event-Triggering Message: Window Notification

The WM-CLOSE message is sent as a signal that a window or an application is terminating.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-CLOSE.


WM-COMMAND

Event-Triggering Message: Window Notification

The WM-COMMAND message is sent to a window when the user selects an item from a menu, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated.

Accelerator keystrokes that are defined to select items from the System menu (also referred to as the Control menu) are translated into WM-SYSCOMMAND messages.

If an accelerator keystroke that corresponds to a menu item occurs when the window that owns the menu is minimized, no WM-COMMAND message is sent. However, if an accelerator keystroke occurs that does not match any of the items on the window’s menu or on the System menu, a WM-COMMAND message is sent even if the window is minimized.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the control sending the message if the message is from a control. Otherwise, the value of this parameter is NULL.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the menu item or control.
WIN-WPARAM-H | windows.cpy | Specifies the notification message if the message is from a control. If the message is from an accelerator, the value of this parameter is 1. If the message is from a menu, the value of this parameter is 0.


WM-CREATE

Event-Triggering Message: Window Notification

The WM-CREATE message is sent when an application requests that a window be created by calling the CREATEWINDOW or CREATEWINDOWEX functions.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-CREATE.


WM-ENABLE

Event-Triggering Message: Window Notification

The WM-ENABLE message is sent when an application changes the enabled state of a window. It is sent to the window whose enabled state is changing. This message is sent after the enabled state (WS-DISABLE style bit) of the window has changed.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-ENABLE.
WIN-WPARAM | windows.cpy | Specifies whether the window has been enabled or disabled. The value of this parameter is WIN-TRUE if the window has been enabled; the value is WIN-FALSE if the window has been disabled.


WM-HSCROLL

Event-Triggering Message: Window Notification

The WM-HSCROLL message is sent to a window when the user clicks the window’s horizontal scroll bar.

The SB-THUMBTRACK scroll bar code typically is used by applications that give some feedback while the scroll box is being dragged.

If an application scrolls the contents of the window, it must also reset the position of the scroll box by using the SETSCROLLPOS function.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-HSCROLL.
WIN-LPARAM | windows.cpy | Contains the handle to the scroll bar control.
WIN-WPARAM-L | windows.cpy | Specifies a scroll bar code that indicates the user’s scrolling request. This parameter can be one of the following values:
 | Value | Meaning
 | SB-ENDSCROLL | Ends scroll.
 | SB-LEFT | Scroll to the upper left.
 | SB-RIGHT | Scroll to the lower right.
 | SB-LINELEFT | Scroll left by one unit.
 | SB-LINERIGHT | Scroll right by one unit.
 | SB-PAGELEFT | Scroll left by the width of the window.
 | SB-PAGERIGHT | Scroll right by the width of the window.
 | SB-THUMBPOSITION | The user has dragged the scroll box (thumb) and released the mouse button. The current position is specified by the WIN-WPARAM-H parameter.
 | SB-THUMBTRACK | The user is dragging the scroll box. This message is sent repeatedly until the user releases the mouse button. The current position is specified by the WIN-WPARAM-H parameter.
WIN-WPARAM-H | windows.cpy | Specifies the current position of the scroll box if WIN-WPARAM-L is SB-THUMBPOSITION or SB-THUMBTRACK; otherwise, this parameter is not used.


WM-KEYDOWN

Event-Triggering Message: Window Notification

The WM-KEYDOWN message is sent when a non-system key is pressed. A non-system key is a key that is pressed when the ALT key is not pressed, or it is a key that is pressed when a window has the input focus.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-KEYDOWN.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code of the given key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-KEYUP

Event-Triggering Message: Window Notification

The WM-KEYUP message is sent when a non-system key is released. A non-system key is a key that is pressed when the ALT key is not pressed, or it is a key that is pressed when a window has the input focus.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-KEYUP.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code of the given key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-KILLFOCUS

Event-Triggering Message: Window Notification

The WM-KILLFOCUS message is sent immediately before a window loses the input focus.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-KILLFOCUS.
WIN-WPARAM | windows.cpy | Identifies the handle to the window that receives the input focus. The value of this parameter may be NULL.


WM-LBUTTONDBLCLK

Event-Triggering Message: Window Notification

The WM-LBUTTONDBLCLK message is sent when the user double-clicks the left mouse button.

Only windows that have the CS-DBLCLKS class style can receive WM-LBUTTONDBLCLK messages. Windows generates a WM-LBUTTONDBLCLK message when the user presses, releases, and again presses the left mouse button within the system’s double-click time limit. Double-clicking the left mouse button actually generates four messages: WM-LBUTTONDOWN, WM-LBUTTONUP, WM-LBUTTONDBLCLK, and another WM-LBUTTONUP.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-LBUTTONDBLCLK.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-LBUTTONDOWN

Event-Triggering Message: Window Notification

The WM-LBUTTONDOWN message is sent when the user presses the left mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-LBUTTONDOWN.
WIN-WPARAM | windows.cpy | Indicates the mouse buttons and keys that the user pressed. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-LBUTTONUP

Event-Triggering Message: Window Notification

The WM-LBUTTONUP message is sent when the user releases the left mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-LBUTTONUP.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-MBUTTONDOWN

Event-Triggering Message: Window Notification

The WM-MBUTTONDOWN message is sent when the user presses the middle mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MBUTTONDOWN.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-MBUTTONUP

Window Management Notification

The WM-MBUTTONUP message is sent when the user releases the middle mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MBUTTONUP.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-PAINT

Event-Triggering Message: Window Notification

The WM-PAINT message is sent when the system or another application makes a request to paint a portion of the application's window.

Parameter | Declaration | Description
HWND | numeric | Handle to the window.


WM-RBUTTONDOWN

Event-Triggering Message: Window Notification

The WM-RBUTTONDOWN message is sent when the user presses the right mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-RBUTTONDOWN.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-RBUTTONUP

Event-Triggering Message: Window Notification

The WM-RBUTTONUP message is sent when the user releases the right mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-RBUTTONUP.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-SETFOCUS

Event-Triggering Message: Window Notification

The WM-SETFOCUS message is sent after a window gains the input focus.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SETFOCUS.
WIN-WPARAM | windows.cpy | Contains the handle of the window that loses the input focus. The value of this parameter may be NULL.


WM-SHOWWINDOW

Event-Triggering Message: Window Notification

The WM-SHOWWINDOW message is sent to a window when it is about to be hidden or shown.

A window is hidden or shown when the SHOWWINDOW function is called, when an overlapped window is maximized or restored, or when an overlapped or pop-up window is minimized or displayed on the screen. When an overlapped window is minimized, all pop-up windows associated with that window are hidden.

The WM-SHOWWINDOW message is not sent under the following circumstances:

· When a top-level (main) window is created with the WS-MAXIMIZE or WS-MINIMIZE style.

· When the SW-SHOWNORMAL flag is specified in the call to the SHOWWINDOW function.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SHOWWINDOW.
WIN-WPARAM | windows.cpy | Specifies whether a window is being shown. It is non-zero if the window is being shown; it is 0 if the window is being hidden.
WIN-LPARAM | windows.cpy | Specifies the status of the window being shown. The value of the WIN-LPARAM parameter is zero if the message is sent because of a SHOWWINDOW function call; otherwise, WIN-LPARAM is one of the following values:
 | Value | Meaning
 | SW-PARENTCLOSING | Parent window is being minimized, or a pop-up window is being hidden.
 | SW-PARENTOPENING | Parent window is opening (being displayed) or a pop-up window is being shown.


WM-SIZE

Event-Triggering Message: Window Notification

The WM-SIZE message is sent to a window after its size has changed.

If the SETSCROLLPOS or MOVEWINDOW function is called for a child window as a result of the WM-SIZE message, the REPAINT parameter for those functions should be nonzero to cause the window to be repainted.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SIZE.
WIN-WPARAM | windows.cpy | Specifies the type of resizing requested. This parameter can be one of the following values:
 | Value | Meaning
 | SIZE-MAXHIDE | Message is sent to all pop-up windows when some other window is maximized.
 | SIZE-MAXIMIZED | Window has been maximized.
 | SIZE-MAXSHOW | Message is sent to all pop-up windows when some other window has been restored to its former size.
 | SIZE-MINIMIZED | Window has been minimized.
 | SIZE-RESTORED | Window has been resized, but neither SIZE-MINIMIZED nor SIZE-MAXIMIZED applies.
WIN-LPARAM-L | windows.cpy | Specifies the new width of the client area.
WIN-LPARAM-H | windows.cpy | Specifies the new height of the client area.


WM-TIMER

Event-Triggering Message: Window Notification

The WM-TIMER message is sent each interval specified in the SETTIMER function used to install a timer.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-TIMER.
WIN-PARAM | windows.cpy | Specifies the identifier of the timer.


WM-VSCROLL

Event-Triggering Message: Window Notification

The WM-VSCROLL message is sent to a window when the user clicks the window’s vertical scroll bar.

The SB-THUMBTRACK scroll bar code typically is used by applications that give some feedback while the scroll box is being dragged.

If an application scrolls the contents of the window, it must also reset the position of the scroll box by using the SETSCROLLPOS function.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-VSCROLL.
WIN-LPARAM | Windows.cpy | Contains the handle of the control if WM-VSCROLL is sent by a scroll bar. If WM-VSCROLL is sent as a result of the user clicking a pop-up window’s scroll bar, the high-order word is not used.
WIN-WPARAM-L | windows.cpy | Specifies a scroll bar code that indicates the user’s scrolling request. This parameter can be one of the following values:
 | Value | Meaning
 | SB-BOTTOM | Scroll to bottom.
 | SB-ENDSCROLL | End scroll.
 | SB-LINEDOWN | Scroll one line down.
 | SB-LINEUP | Scroll one line up.
 | SB-PAGEDOWN | Scroll one page down.
 | SB-PAGEUP | Scroll one page up.
 | SB-THUMBPOSITION | Scroll to absolute position. The current position is specified by the WIN-WPARAM-H parameter.
 | SB-THUMBTRACK | Drag scroll box (thumb) to specified position. The current position is specified by the WIN-WPARAM-H parameter.
 | SB-TOP | Scroll to top.
WIN-WPARAM-H | windows.cpy | Specifies the current position of the scroll box if WIN-WPARAM-L is SB-THUMBPOSITION or SB-THUMBTRACK; otherwise, this parameter is not used.


Automatically-Processed Messages

See Also

Some messages neither trigger events nor manipulate objects, but rather are used to by WOW Extensions in interpreting communications with Windows. These messages are automatically processed and are handled internally by WOW Extensions.

The following table summarizes the automatically processed messages.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
WM-DESTROY | Sent when a form is being destroyed.
WM-MOUSEACTIVATE | Sent when the cursor is in an inactive form and the user presses a mouse button.
WM-SYSCHAR | Sent to the form with the input focus when a WM-SYSKEYUP and a WM-SYSKEYDOWN message are translated.
WM-SYSCOLORCHANGE | Sent to all top-level forms when a change is made in the system color setting.
WM-SYSKEYDOWN | Sent to the form with the input focus when the user holds down the Alt key and then presses another key.
WM-SYSKEYUP | Sent to the form with the input focus when the user releases a key that was pressed while the Alt key was held down.


WM-DESTROY

Automatically-Processed Message: Window Management

The WM-DESTROY message is sent when a window is being destroyed. It is sent to the window procedure of the window being destroyed after the window is removed from the screen.

This message is sent first to the window being destroyed and then to the child windows (if any) as they are destroyed.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-DESTROY.


WM-MOUSEACTIVATE

Automatically-Processed Message: Window Input

The WM-MOUSEACTIVATE message is sent when the cursor is in an inactive window and the user presses a mouse button.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MOUSEACTIVATE.
WIN-WPARAM | windows.cpy | Contains the handle of the top-level parent window of the window being activated.
WIN-LPARAM-L | windows.cpy | Specifies the hit-test area code. A hit test is a test that determines the location of the cursor.
WIN-LPARAM-H | windows.cpy | Specifies the identifier of the mouse message.


WM-SYSCHAR

Automatically-Processed Message: Window System

The WM-SYSCHAR message is sent to the window with the input focus when a WM-SYSKEYUP and a WM-SYSKEYDOWN message are translated. It specifies the virtual-key code of the System-menu key. (The System menu is also referred to as the Control menu.)

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSCHAR.
WIN-WPARAM | windows.cpy | Specifies the ASCII-character key code of a System-menu key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-SYSCOLORCHANGE

Automatically-Processed Message: Window System

The WM-SYSCOLORCHANGE message is sent to all top-level windows when a change is made in the system color setting.

Windows sends a WM-PAINT message to any window that is affected by a system color change.

Applications that have brushes using the existing system colors should delete those brushes and re-create them by using the new system colors.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSCOLORCHANGE.


WM-SYSKEYDOWN

Automatically-Processed Message: Window System

The WM-SYSKEYDOWN message is sent to the window with the input focus when the user holds down the ALT key and then presses another key. If no window currently has the input focus, the WM-SYSKEYDOWN message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the WIN-LPARAM-H parameter.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSKEYDOWN.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code of the key being pressed.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-SYSKEYUP

Automatically-Processed Message: Window System

The WM-SYSKEYUP message is sent to the window with the input focus when the user releases a key that was pressed while the ALT key was held down. If no window currently has the input focus, the WM-SYSKEYUP message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the WIN-LPARAM-H parameter.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSKEYUP.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code of the key being pressed.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


Information-Only Messages

See Also

The Windows operating system uses messages extensively, but not all Windows messages are used by WOW Extensions. Should a developer need to write code that might send or receive messages outside the normal WOW development scheme, Liant has documented certain messages for information purposes only. They included here for the sake of completeness.

The following table summarizes the messages that are used for information only.

Note The detailed explanation of each message discusses its purpose, illustrates the calling sequence, lists and describes each parameter, and provides special comments and usage notes, where necessary.

Message | Description
BN-DISABLE | Sent when a button is disabled
CBN-CLOSEUP | Sent when the list box portion of a combo box is hidden
CBN-EDITUPDATE | Sent when the edit box portion of a combo box is about to display altered text.
CBN-SELENDCANCEL | Sent when the user clicks an item and then clicks another form or control to hide the list box portion of a combo box.
CBN-SELENDOK | Sent when the user selects an item and then either presses the Enter key or clicks the Down Arrow key to hide the list box portion of a combo box.
EN-UPDATE | Sent when an edit box control is about to display altered text.
LBN-ERRSPACE | Sent when a list box cannot allocate enough memory to meet a specific request.
LBN-SELCANCEL | Sent when the user cancels the selection in a list box.
WM-ACTIVATEAPP | Sent when a form is about to be activated and that form belongs to a different task than the active form.
WM-CHARTOITEM | Sent by a list box to its owner in response to a WM-CHAR message.
WM-COMPACTING | Sent to all top-level forms when Windows detects that more than 12.5 percent of system time over a 30- to 60-second interval is being spent compacting memory.
WM-DEADCHAR | Sent when a WM-KEYUP message and a WM-KEYDOWN message are translated.
WM-DESTROY | Sent when a form is being destroyed.
WM-MBUTTONDBLCLK | Sent when the user double-clicks the middle mouse button.
WM-MENUSELECT | Sent to the form associated with a menu when the user selects a menu item.
WM-MOVE | Sent after a form has been moved.
WM-PARENTNOTIFY | Sent to the parent of a child window when the child window is created or destroyed, or when the user clicks a mouse button while the cursor is over the child window.
WM-POWER | Sent when the system, typically a battery-powered personal computer, is about to enter the suspended mode.
WM-RBUTTONDBLCLK | Sent when the user double-clicks the right mouse button.
WM-SPOOLERSTATUS | Sent from Print Manager whenever a job is added to or removed from the Print Manager queue.
WM-SYSCOMMAND | Sent when the user selects a command from the System menu (also referred to as the Control menu) or when the user selects the Maximize or the Minimize button.
WM-SYSDEADCHAR | Sent to the form with the input focus when WM-SYSKEYUP and WM-SYSKEYDOWN messages are translated.
WM-TIMECHANGE | Sent to all top-level forms after changing the system time.
WM-VKEYTOITEM | Sent by a list box to its owner in response to a WM-KEYDOWN message.
WM-WINDOWPOSCHANGED | Sent to a form whose size, position, or z-order has changed as a result of a call to one of the Windows API window functions.
WM-WININICHANGE | Sent to all top-level forms after making a change to the Windows initialization file, win.ini.


BN-DISABLE

Information-Only Message: Button Notification

The BN-DISABLE notification message is sent to the parent window when a button contained by the window is disabled. This notification is provided for compatibility with applications written prior to Windows version 3.0.


CBN-CLOSEUP

Information-Only Message: Combo Box Notification

The CBN-CLOSEUP notification message is sent when the list box of a combo box is hidden. The parent window of the combo box receives this notification message through a WM-COMMAND message.

This notification message is not sent to a combo box that has the CBS-SIMPLE style.

The order in which notifications will be sent cannot be predicted. In particular, a CBN-SELCHANGE notification message may occur either before or after a CBN-CLOSEUP notification.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-CLOSEUP notification message.


CBN-EDITUPDATE

Information-Only Message: Combo Box Notification

The CBN-EDITUPDATE notification message is sent when the edit box control portion of a combo box is about to display altered text. This notification is sent after the control has formatted the text, but before it displays the text. The parent window of the combo box receives this notification message through a WM-COMMAND message.

This message does not occur if the combo box has the CBS-DROPDOWNLIST style.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-EDITUPDATE notification message.


CBN-SELENDCANCEL

Information-Only Message: Combo Box Notification

The CBN-SELENDCANCEL notification message is sent when the user clicks an item and then clicks another window or control to hide the list box of a combo box. This notification message is sent before the CBN-CLOSEUP notification message to indicate that the user’s selection should be ignored.

The CBN-SELENDCANCEL or CBN-SELENDOK notification message is sent even if the CBN-CLOSEUP notification message is not sent (as in the case of a combo box with the CBS-SIMPLE style).

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-SELENDCANCEL notification message.


CBN-SELENDOK

Information-Only Message: Combo Box Notification

The CBN-SELENDOK notification message is sent when the user selects an item and then either presses the ENTER key or clicks the DOWN ARROW key to hide the list box of a combo box. This notification message is sent before the CBN-CLOSEUP notification message to indicate that the user’s selection should be considered valid.

The CBN-SELENDOK or CBN-SELENDCANCEL notification message is sent even if the CBN-CLOSEUP notification message is not sent (as in the case of a combo box with the CBS-SIMPLE style).

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the combo box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the combo box.
WIN-WPARAM-H | windows.cpy | Specifies the CBN-SELENDOK notification message.


EN-UPDATE

Information-Only Message: Edit Box Notification

The EN-UPDATE notification message is sent when an edit box control is about to display altered text. This notification is sent after the control has formatted the text but before it screens the text. This makes it possible to alter the window size, if necessary. The control’s parent window receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the edit box control.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the edit box control.
WIN-WPARAM-H | windows.cpy | Specifies the EN-UPDATE notification message in the high-order word.


LBN-ERRSPACE

Information-Only Message: List Box Notification

The LBN-ERRSPACE notification message is sent when a list box cannot allocate enough memory to meet a specific request. The parent window of the list box receives this notification message through a WM-COMMAND message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the LBN-ERRSPACE notification message.


LBN-SELCANCEL

Information-Only Message: List Box Notification

The LBN-SELCANCEL notification message is sent when the user cancels the selection in a list box. The parent window of the list box receives this notification message through a WM-COMMAND message.

This notification applies only to a list box that has the LBS-NOTIFY style.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMMAND.
WIN-LPARAM | windows.cpy | Contains the handle of list box.
WIN-WPARAM-L | windows.cpy | Specifies the identifier of the list box.
WIN-WPARAM-H | windows.cpy | Specifies the LBN-SELCANCEL notification message.


WM-ACTIVATEAPP

Information-Only Message: Window Management

The WM-ACTIVATEAPP message is sent when a window is about to be activated and that window belongs to a different task than the active window. The message is sent to all top-level windows of the task being activated and to all top-level windows of the task being deactivated.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-ACTIVATEAPP.
WIN-LPARAM | windows.cpy | Specifies a task handle. If the WIN-WPARAM parameter is nonzero, the handle identifies the task that owns the window being deactivated. If WIN-WPARAM is zero, the handle identifies the task that owns the window being activated.
WIN-WPARAM | windows.cpy | Specifies whether the window is being activated or deactivated. A nonzero value means the window is being activated. A zero value means the window is being deactivated.


WM-CHARTOITEM

Information-Only Message: Window Input

The WM-CHARTOITEM message is sent by a list box with the LBS-WANTKEYBOARDINPUT style to its owner in response to a WM-CHAR message.

Only owner-drawn list boxes that do not have the LBS-HASSTRINGS style can receive this message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-CHARTOITEM.
WIN-LPARAM | windows.cpy | Contains the handle of the list box.
WIN-WPARAM-L | windows.cpy | Specifies the value of the key the user pressed.
WIN-WPARAM-H | windows.cpy | Specifies the current caret position.


WM-COMPACTING

Information-Only Message: Window System

The WM-COMPACTING message is sent to all top-level windows when Windows detects that more than 12.5 percent of system time over a 30- to 60-second interval is being spent compacting memory. This indicates that system memory is low.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-COMPACTING.
WIN-WPARAM | windows.cpy | Specifies the ratio of central processing unit (CPU) time currently spent by Windows compacting memory to CPU time currently spent by Windows performing other operations. For example, 0x8000 represents 50 percent of CPU time spent compacting memory.


WM-DEADCHAR

Information-Only Message: Window Input

The WM-DEADCHAR message is sent to the windows when a WM-KEYUP message and a WM-KEYDOWN message are translated. It specifies the character value of a dead key. A dead key is a key, such as the umlaut (double-dot) character, that is combined with other characters to form a composite character. For example, the umlaut-O character consists of the dead key, umlaut, and the O key.

An application typically uses the WM-DEADCHAR message to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-DEADCHAR.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code value of the dead key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-MBUTTONDBLCLK

Information-Only Message: Window Input

The WM-MBUTTONDBLCLK message is sent when the user double-clicks the middle mouse button.

Only windows that have the CS-DLBCLKS class style can receive WM-MBUTTONDBLCLK messages. Windows generates a WM-MBUTTONDBLCLK message when the user presses, releases, and presses the middle mouse button within the system’s double-click time limit. Double-clicking the middle mouse button actually generates two messages: WM-MBUTTONDOWN and WM-MBUTTONDBLCLK.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MBUTTONDBLCLK.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-MENUSELECT

Information-Only Message: Window Management

The WM-MENUSELECT message is sent to the window associated with a menu when the user selects a menu item.

If the WIN-WPARAM-L parameter contains -1 and the WIN-WPARAM-H parameter contains 0, Windows has closed the menu. This occurs both when the menu is closed because the user pressed ESC or clicked outside the menu and when the user has selected a menu item.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MENUSELECT.
WIN-LPARAM | windows.cpy | Contains the handle to the menu that was clicked.
WIN-WPARAM-L | windows.cpy | Specifies the menu item or submenu index.
WIN-WPARAM-H | windows.cpy | Specifies one or more menu flags. This parameter can be one or more of the following values:
 | Flag | Meaning
 | MF-BITMAP | Item is a bitmap.
 | MF-CHECKED | Item is checked.
 | MF-DISABLED | Item is disabled.
 | MF-GRAYED | Item is grayed.
 | MF-HILITE | Item is highlighted.
 | MF-MOUSESELECT | Item is selected with a mouse.
 | MF-OWNERDRAW | Item is an owner-drawn item.
 | MF-POPUP | Item contains a pop-up menu.
 | MF-SYSMENU | Item is contained in the System menu (also referred to as the Control menu). The WIN-LPARAM parameter contains a handle that identifies the System menu associated with the message.


WM-MOVE

Information-Only Message: Window Management

The WM-MOVE message is sent after a window has been moved.

The WIN-LPARAM-L and WIN-LPARAM-H parameters are given in screen coordinates for overlapped and pop-up windows, and in parent-client coordinates for child windows.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-MOVE.
WIN-LPARAM-L | windows.cpy | Specifies the new x-coordinate of the upper-left corner of the client area of the window.
WIN-LPARAM-H | windows.cpy | Specifies the new y-coordinate of the upper-left corner of the client area of the window.


WM-PARENTNOTIFY

Information-Only Message: Window Management

The WM-PARENTNOTIFY message is sent to the parent of a child window when the child window is created or destroyed or when the user clicks a mouse button while the cursor is over the child window. When the child window is being created, the system sends WM-PARENTNOTIFY just before the CREATEWINDOW or CREATEWINDOWEX function that creates the window returns. When the child window is being destroyed, the system sends the message before any processing to destroy the window takes place.

This message is also sent to all ancestor windows of the child window, including the top-level window.

All child windows, except those that have the WS-EX-NOPARENTNOTIFY extended window style, send this message to their parent windows. By default, child windows in a dialog box have the WS-EX-NOPARENTNOTIFY style, unless the CREATEWINDOWEX function was called to create the child window without this style.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-PARENTNOTIFY.
WIN-LPARAM | windows.cpy | The meaning of WIN-LPARAM depends on the value of WIN-WPARAM-L. It can be any of the following values:
 | Value | Meaning
 | WM-CREATE | Handle of the child window.
 | WM-DESTROY | Handle of the child window.
 | WM-LBUTTONDOWN | The x-coordinate of the cursor is the low-order word, and the y-coordinate of the cursor is the high-order word.
 | WM-MBUTTONDOWN | The x-coordinate of the cursor is the low-order word, and the y-coordinate of the cursor is the high-order word.
 | WM-RBUTTONDOWN | The x-coordinate of the cursor is the low-order word, and the y-coordinate of the cursor is the high-order word.
WIN-WPARAM-L | windows.cpy | Specifies the event for which the parent is being notified. It can be any of the following values:
 | Value | Meaning
 | WM-CREATE | The child window is being created.
 | WM-DESTROY | The child window is being destroyed.
 | WM-LBUTTONDOWN | The user has placed the mouse cursor over the child window and clicked the left mouse button.
 | WM-MBUTTONDOWN | The user has placed the mouse cursor over the child window and clicked the middle mouse button.
 | WM-RBUTTONDOWN | The user has placed the mouse cursor over the child window and clicked the right mouse button.
WIN-WPARAM-H | windows.cpy | Depends on the value of WIN-WPARAM-L. It can be any of the following values:
 | Value | Meaning
 | WM-CREATE | Identifier of the child window.
 | WM-DESTROY | Identifier of the child window.
 | WM-LBUTTONDOWN | Undefined.
 | WM-MBUTTONDOWN | Undefined.
 | WM-RBUTTONDOWN | Undefined.


WM-POWER

Information-Only Message: Window System

The WM-POWER message is sent when the system, typically a battery-powered personal computer, is about to enter suspended mode.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-POWER.
WIN-WPARAM | windows.cpy | Specifies a power-event notification message. This parameter may be one of the following values:
 | Value | Meaning
 | PWR-CRITICALRESUME | Indicates that the system is resuming operation after entering the suspended mode without first sending a PWR-SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.
 | PWR-SUSPENDREQUEST | Indicates that the system is about to enter the suspended mode.
 | PWR-SUSPENDRESUME | Indicates that the system is resuming operation after entering the suspended mode normally -- that is, the system sent a PWR-SUSPENDREQUEST notification message to the application before the system was suspended. An application should perform any necessary recovery actions.


WM-RBUTTONDBLCLK

Information-Only Message: Window Input

The WM-RBUTTONDBLCLK message is sent when the user double-clicks the right mouse button.

Only windows that have the CS-DBLCLKS class style can receive WM-RBUTTONDBLCLK messages. Windows generates a WM-RBUTTONDBLCLK message when the user presses, releases, and again presses the right mouse button within the system’s double-click limit. Double-clicking the right mouse button actually generates four messages: WM-RBUTTONDOWN, WM-RBUTTONUP, WM-RBUTTONDBLCLK, and another WM-RBUTTONUP.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-RBUTTONDBLCLK.
WIN-WPARAM | windows.cpy | Indicates whether various virtual keys are down. This parameter can be one or more of the following values:
 | Value | Meaning
 | MK-CONTROL | The user pressed the CTRL key.
 | MK-LBUTTON | The user pressed the left mouse button.
 | MK-MBUTTON | The user pressed the middle mouse button.
 | MK-RBUTTON | The user pressed the right mouse button.
 | MK-SHIFT | The user pressed the SHIFT key.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the window.


WM-SPOOLERSTATUS

Information-Only Message: Window System

The WM-SPOOLERSTATUS message is sent from the Print Manager whenever a job is added to or removed from the Print Manager queue.

This message is for informational purposes only.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SPOOLERSTATUS.
WIN-WPARAM | windows.cpy | Specifies the status of the job.
WIN-LPARAM-L | windows.cpy | Specifies the number of jobs remaining in the Print Manager queue.


WM-SYSCOMMAND

Information-Only Message: Window System

The WM-SYSCOMMAND message is sent when the user chooses a command from the System menu (also referred to as the Control menu) or when the user chooses the Maximize button, Minimize button, Restore button, or Close button.

In WM-SYSCOMMAND messages, the four low-order bits of the WIN-WPARAM parameter are used internally by Windows. When an application tests the value of WIN-WPARAM, it must combine the value 0xFFF0 with the WIN-WPARAM value by using the bitwise AND operator to obtain the correct result.

The menu items in a System menu can be modified by using the APPENDMENU, INSERTMENU, MODIFYMENU and SETFOCUS functions. Applications that modify the System menu must process WM-SYSCOMMAND messages.

Accelerator keystrokes that are defined to choose items from the System menu are translated into WM-SYSCOMMAND messages; all other accelerator keystrokes are translated into WM-COMMAND messages.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSCOMMAND.
WIN-WPARAM | windows.cpy | Specifies the type of system command requested. This parameter can be one of the following values:
 | Value | Meaning
 | SC-CLOSE | Close the window.
 | SC-HOTKEY | Activate the window associated with the application-specified hot key. The low-order word in WIN-LPARAM-L identifies the window to activate.
 | SC-HSCROLL | Scroll horizontally.
 | SC-KEYMENU | Retrieves a menu through a keystroke.
 | SC-MAXIMIZE (or SC-ZOOM) | Maximize the window.
 | SC-MINIMIZE (or SC-ICON) | Minimize the window.
 | SC-MOUSEMENU | Retrieve a menu through a mouse click.
 | SC-MOVE | Move the window.
 | SC-NEXTWINDOW | Move to the next window.
 | SC-PREVWINDOW | Move to the previous window.
 | SC-RESTORE | Restore window to normal position and size.
 | SC-SCREENSAVE | Execute the screen-saver application specified in the [boot] section of the SYSTEM.INI file.
 | SC-SIZE | Size the window.
 | SC-TASKLIST | Execute or activate the Windows Task Manager (Start menu) application.
 | SC-VSCROLL | Scroll vertically.
WIN-LPARAM-L | windows.cpy | Specifies the x-coordinate of the cursor, if a System-menu command is chosen with the mouse. Otherwise, this parameter is not used.
WIN-LPARAM-H | windows.cpy | Specifies the y-coordinate of the cursor, if a System-menu command is chosen with the mouse. Otherwise, this parameter is not used.


WM-SYSDEADCHAR

Information-Only Message: Window System

The WM-SYSDEADCHAR message is sent to the window with the input focus when WM-SYSKEYUP and WM-SYSKEYDOWN messages are translated. It specifies the character value of a dead key.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-SYSDEADCHAR.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code value of the dead key.
WIN-LPARAM-L | windows.cpy | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
WIN-LPARAM-H | windows.cpy | Specifies the context code, previous key-state flag, and transition-state flag, as follows:
 | Value | Meaning
 | 13 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
 | 14 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
 | 15 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.


WM-TIMECHANGE

Information-Only Message: Window System

An application sends the WM-TIMECHANGE message to all top-level windows after changing the system time.

Any application that changes the system time should send this message to all top-level windows. To send the WM-TIMECHANGE message to all top-level windows, an application can use the SENDMESSAGE function with the WND-H parameter set to HWND-BROADCAST.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-TIMECHANGE.


WM-VKEYTOITEM

Information-Only Message: Window Input

The WM-VKEYTOITEM message is sent by a list box with the LBS-WANTKEYBOARDINPUT style to its owner in response to a WM-KEYDOWN message.

Only list boxes that have the LBS-HASSTRINGS style can receive this message.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-VKEYTOITEM.
WIN-WPARAM | windows.cpy | Specifies the virtual-key code of the key that the user pressed.
WIN-LPARAM-L | windows.cpy | Contains the handle of the list box.
WIN-LPARAM-H | windows.cpy | Specifies the current position of the caret.


WM-WINDOWPOSCHANGED

Information-Only Message: Window Management

The WM-WINDOWPOSCHANGED message is sent to a window whose size, position, or place in the z-order has changed as a result of a call to one of the Windows API window functions.

When it processes the WM-WINDOWPOSCHANGED message, Windows sends the WM-SIZE and WM-MOVE messages to the window.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-WINDOWPOSCHANGED.
WIN-LPARAM | windows.cpy | Points to a WINDOWPOS data structure that contains information about the window’s new size and position.


WM-WININICHANGE

Information-Only Message: Window System

An application sends the WM-WININICHANGE message to all top-level windows after making a change to the Windows initialization file, win.ini.

To send the WM-WININICHANGE message to all top-level windows, an application can use the SENDMESSAGE function with the WND-H parameter set to a value of HWND-BROADCAST.

If an application changes many different sections in win.ini at the same time, the application should send the WM-WININICHANGE message once with the WIN-LPARAM parameter set to NULL. Otherwise, an application should send a separate WM-WININICHANGE message for each change it makes to win.ini.

If an application receives a WM-WININICHANGE message with the WIN-LPARAM parameter set to NULL, the application should check all sections in win.ini that affect the application.

Parameter | Declaration | Description
WIN-MSG-HANDLE | windows.cpy | Contains a handle that identifies the window to which the message was sent.
WIN-MSG-ID | windows.cpy | Identifies the message as WM-WININICHANGE.
WIN-LPARAM | windows.cpy | Points to a string that specifies the name of the section that has changed (the string does not include the square brackets that enclose the section name).


Undocumented Message

At the time of the general release, this message has not been documented. Contact Liant Customer Support for more information.


Reference

Functions Listed Alphabetically


Functions Listed Alphabetically

See Also

The functions used in WOW Extensions are listed below alphabetically. You can either browse through this list of functions or click one of the buttons to locate a particular function more quickly.

Note WOW Extensions provides code templates for the functions so that it is easier to understand what the parameters are for a particular function. The available templates are listed in the Code Templates tree on the WOW Designer window.

A

ANSITOOEM

ANSITOOEMBUFF

APPENDMENU

AXDOMETHOD

AXGETAXHANDLE

AXGETCLASSID

AXGETGUID

AXGETHWND

AXGETINDEXPROP

AXSETINDEXPROP

C

CHECKDLGBUTTON

CHECKMENUITEM

CHECKRADIOBUTTON

CLIENTTOSCREEN

CLOSEWINDOW

CREATEFONTINDIRECT

CREATEIC

CREATEMENU

CREATEPOPUPMENU

CREATEWINDOW or
CREATEWINDOWEX

D

DELETEDC

DELETEMENU

DELETEOBJECT

DESTROYICON

DESTROYMENU

DESTROYWINDOW

DLGDIRLIST

DLGDIRLISTCOMBOBOX

DLGDIRSELECT or
DLGDIRSELECTEX

DLGDIRSELECTCOMBOBOX or
DLGDIRSELECTCOMBOBOXEX

DRAWMENUBAR

E - F

ENABLEMENUITEM

ENABLEWINDOW

FINDWINDOW

FLASHWINDOW

G

GETACTIVEWINDOW | GETASYNCKEYSTATE | GETCHARWIDTH
GETCLASSINFO | GETCLASSLONG | GETCLASSNAME
GETCLASSWORD | GETCLIENTADDR | GETCLIENTARGS
GETCLIENTRECT | GETCURRENTTASK | GETCURRENTTIME
GETCURSORPOS | GETDEVICECAPS | GETDIALOGBASEUNITS
GETDLGCTRLID | GETDLGITEM | GETDLGITEMINT
GETDLGITEMTEXT | GETDOSENVIRONMENT | GETDRIVETYPE
GETENVIRONMENTVARIABLE | GETFOCUS | GETINPUTSTATE
GETKEYBOARDSTATE | GETKEYBOARDTYPE | GETKEYNAMETEXT
GETKEYSTATE | GETMENU | GETMENUITEMCOUNT
GETMENUITEMID | GETMENUSTATE | GETMENUSTRING
GETNEARESTCOLOR | GETNEXTDLGGROUPITEM | GETNEXTDLGTABITEM
GETPARENT | GETPRIVATEPROFILEINT | GETPRIVATEPROFILESECTION
GETPRIVATEPROFILESTRING | GETPROFILEINT | GETPROFILESECTION
GETPROFILESTRING | GETSCROLLPOS | GETSCROLLRANGE
GETSTOCKOBJECT | GETSUBMENU | GETSYSCOLOR
GETSYSTEMDIRECTORY | GETSYSTEMMENU | GETSYSTEMMETRICS
GETTEMPFILENAME | GETTEMPPATH | GETTEXTMETRICS
GETTOPWINDOW | GETVERSION | GETVERSIONEX
GETWINDOW | GETWINDOWLONG | GETWINDOWRECT
GETWINDOWSDIRECTORY | GETWINDOWTEXT | GETWINDOWTEXTLENGTH
GETWINDOWWORD |  |

H - I

HILITEMENUITEM

HTMLHELP

INSERTMENU

ISCHARALPHA

ISCHARALPHANUMERIC

ISCHARLOWER

ISCHARUPPER

ISCHILD

ISDLGBUTTONCHECKED

ISICONIC

ISMENU

ISWINDOW

ISWINDOWENABLED

ISWINDOWVISIBLE

ISZOOMED

K - L

KILLTIMER

LOCKWINDOWUPDATE

M

MESSAGEBEEP

MESSAGEBOX

MODIFYMENU

MOVEWINDOW

O - P

OEMTOANSI

OEMTOANSIBUFF

OPENICON

POSTMESSAGE

R

REGISTERCLASS

RELEASECAPTURE

REMOTECOMMAND

REMOTECOPY

REMOTESHELLEXECUTE

REMOVEMENU

S

SCREENTOCLIENT

SENDMESSAGE

SETACTIVEWINDOW

SETCAPTURE

SETCLASSLONG

SETCLASSWORD

SETCURSORPOS

SETDLGITEMINT

SETDLGITEMTEXT

SETENVIRONMENTVARIABLE

SETFOCUS

SETFOREGROUNDWINDOW

SETKEYBOARDSTATE

SETLOCALEMONETARY

SETLOCALENUMERIC

SETMENU

SETMENUITEMBITMAPS

SETPARENT

SETSCROLLPOS

SETSCROLLRANGE

SETTIMER

SETWINDOWLONG

SETWINDOWTEXT

SETWINDOWWORD

SHOWOWNEDPOPUPS

SHOWSCROLLBAR

SHOWWINDOW

T - V

TRACKPOPUPMENU

UNREGISTERCLASS

UPDATEWINDOW

VKKEYSCAN

W

WINEXEC | WINHELP | WOWADDITEM
WOWADDMULTIPLESTRINGS | WOWCLEAR | WOWCLEARWAITCURSOR
WOWCREATEWINDOW | WOWDESTROYWINDOW | WOWDISCARDEVENTS
WOWENDMODAL | WOWFORMTOWOWVERSION | WOWGETCOBOLHWND
WOWGETFOCUS | WOWGETFONTS | WOWGETINDEXPROP
WOWGETMESSAGE | WOWGETNUM | WOWGETPROP
WOWGETWINDOWTYPE | WOWGLOBALMEMORYSTATUS | WOWINITALLCONTROLS
WOWINITCONTROL | WOWINPUTBOX | WOWLOADBITMAP
WOWLOADICON | WOWESSAGEBOX | WOWMOVE
WOWMULTICONTROLGETPROP | WOWMULTICONTROLSETPROP | WOWPEEKMESSAGE
WOWREFRESH | WOWREMOVEITEM | WOWRESETWAITCURSOR
WOWSETFOCUS | WOWSETINDEXPROP | WOWSETNEXTCTRL
WOWSETNUM | WOWSETPREVCTRL | WOWSETPROP
WOWSETSTRIPTRAILING | WOWSETWAITCURSOR | WOWSTARTMODAL
WOWTHINCLIENTREMOTEPROGRAM | WOWTHINCLIENTSETNOWAIT | WOWVERSION
WRITEPRIVATEPROFILESECTION | WRITEPRIVATEPROFILESTRING | WRITEPROFILESECTION
WRITEPROFILESTRING |  |


Messages Listed Alphabetically

See Also

The messages used in WOW Extensions are listed below alphabetically with their prefixes. You can either browse through this list of messages or click one of the buttons to locate a particular message more quickly.

Note WOW Extensions provides code templates, also called shortcuts, for frequently-used messages so that it is easier to understand what the parameters are for a particular message. The available shortcuts are listed in the Code Templates tree on the WOW Designer window.

A - B

ACM-OPEN

ACM-PLAY

ACM-STOP

BM-GETCHECK

BM-GETSTATE

BM-SETCHECK

BM-SETSTATE

BM-SETSTYLE

BN-CLICKED

BN-DISABLE

BN-DOUBLECLICKED

C

CB-ADDSTRING | CB-DELETESTRING | CB-DIR
CB-FINDSTRING | CB-FINDSTRINGEXACT | CB-GETCOUNT
CB-GETCURSEL | CB-GETDROPPEDCONTROLRECT | CB-GETDROPPEDSTATE
CB-GETEDITSEL | CB-GETEXTENDEDUI | CB-GETITEMHEIGHT
CB-GETLBTEXT | CB-GETLBTEXTLEN | CB-INSERTSTRING
CB-LIMITTEXT | CB-RESETCONTENT | CB-SELECTSTRING
CB-SETCURSEL | CB-SETEDITSEL | CB-SETEXTENDEDUI
CB-SETITEMHEIGHT | CB-SHOWDROPDOWN | CBN-CLOSEUP
CBN-DBLCLK | CBN-DROPDOWN | CBN-EDITCHANGE
CBN-EDITUPDATE | CBN-ERRSPACE | CBN-KILLFOCUS
CBN-SELCHANGE | CBN-SELENDCANCEL | CBN-SELENDOK
CBN-SETFOCUS |  |

E

EM-CANUNDO | EM-EMPTYUNDOBUFFER | EM-FMTLINES
EM-GETFIRSTVISIBLELINE | EM-GETLINE | EM-GETLINECOUNT
EM-GETMODIFY | EM-GETPASSWORDCHAR | EM-GETRECT
EM-GETSEL | EM-LIMITTEXT | EM-LINEFROMCHAR
EM-LINEINDEX | EM-LINELENGTH | EM-LINESCROLL
EM-REPLACESEL | EM-SETMODIFY | EM-SETPASSWORDCHAR
EM-SETREADONLY | EM-SETRECT | EM-SETRECTNP
EM-SETSEL | EM-SETTABSTOPS | EM-UNDO
EN-CHANGE | EN-ERRSPACE | EN-HSCROLL
EN-KILLFOCUS | EN-MAXTEXT | EN-SETFOCUS
EN-UPDATE | EN-VSCROLL |

L

LB-ADDSTRING | LB-DELETESTRING | LB-DIR
LB-FINDSTRING | LB-FINDSTRINGEXACT | LB-GETCARETINDEX
LB-GETCURSEL | LB-GETHORIZONTALEXTENT | LB-GETITEMHEIGHT
LB-GETITEMRECT | LB-GETSEL | LB-GETSELCOUNT
LB-GETSELITEMS | LB-GETTEXT | LB-GETTEXTLEN
LB-GETTOPINDEX | LB-INSERTSTRING | LB-RESETCONTENT
LB-SELECTSTRING | LB-SELITEMRANGE | LB-SETCARETINDEX
LB-SETCOLUMNWIDTH | LB-SETCURSEL | LB-SETHORIZONTALEXTENT
LB-SETITEMHEIGHT | LB-SETSEL | LB-SETTABSTOPS
LB-SETTOPINDEX | LBN-DBLCLK | LBN-ERRSPACE
LBN-KILLFOCUS | LBN-SELCANCEL | LBN-SELCHANGE
LBN-SETFOCUS |  |

P

PBM-DELTAPOS

PBM-SETPOS

PBM-SETRANGE32

PBM-SETSTEP

PBM-STEPIT

W

WM-ACTIVATE | WM-ACTIVATEAPP | WM-CHAR
WM-CHARTOITEM | WM-CLEAR | WM-CLOSE
WM-COMMAND | WM-COMPACTING | WM-COPY
WM-CREATE | WM-CUT | WM-DEADCHAR
WM-DESTROY | WM-ENABLE | WM-FONTCHANGE
WM-GETFONT | WM-GETICON | WM-GETTEXT
WM-GETTEXTLENGTH | WM-HSCROLL | WM-KEYDOWN
WM-KEYUP | WM-KILLFOCUS | WM-LBUTTONDBLCLK
WM-LBUTTONDOWN | WM-LBUTTONUP | WM-MBUTTONDBLCLK
WM-MBUTTONDOWN | WM-MBUTTONUP | WM-MENUSELECT
WM-MOUSEACTIVATE | WM-MOVE | WM-NEXTDLGCTL
WM-PAINT | WM-PARENTNOTIFY | WM-PASTE
WM-POWER | WM-RBUTTONDBLCLK | WM-RBUTTONDOWN
WM-RBUTTONUP | WM-SETFOCUS | WM-SETFONT
WM-SETICON | WM-SETREDRAW | WM-SETTEXT
WM-SHOWWINDOW | WM-SIZE | WM-SPOOLERSTATUS
WM-SYSCHAR | WM-SYSCOLORCHANGE | WM-SYSCOMMAND
WM-SYSDEADCHAR | WM-SYSKEYDOWN | WM-SYSKEYUP
WM-TIMECHANGE | WM-TIMER | WM-UNDO
WM-VKEYTOITEM | WM-VSCROLL | WM-WINDOWPOSCHANGED
WM-WININICHANGE |  |


A-B Messages

ACM-OPEN

ACM-PLAY

ACM-STOP

BM-GETCHECK

BM-GETSTATE

BM-SETCHECK

BM-SETSTATE

BM-SETSTYLE

BN-CLICKED

BN-DISABLE

BN-DOUBLECLICKED


ActiveX Functions See Also

Using Functions in WOW Extensions

WOW Functions


A Functions

ANSITOOEM

ANSITOOEMBUFF

APPENDMENU

AXDOMETHOD

AXGETAXHANDLE

AXGETCLASSID

AXGETGUID

AXGETHWND

AXGETINDEXPROP

AXSETINDEXPROP


Animation Control Messages See Also

Object-Manipulation Messages


Automatically-Processed Messages See Also

Event-Triggering Messages

Information-Only Messages

Object-Manipulation Messages


Button Messages See Also

Object-Manipulation Messages


Button Notification Messages See Also

Event-Triggering Messages


C Functions

CHECKDLGBUTTON

CHECKMENUITEM

CHECKRADIOBUTTON

CLIENTTOSCREEN

CLOSEWINDOW

CREATEFONTINDIRECT

CREATEIC

CREATEMENU

CREATEPOPUPMENU

CREATEWINDOW or
CREATEWINDOWEX


C Messages

CB-ADDSTRING

CB-DELETESTRING

CB-DIR

CB-FINDSTRING

CB-FINDSTRINGEXACT

CB-GETCOUNT

CB-GETCURSEL

CB-GETDROPPEDCONTROLRECT

CB-GETDROPPEDSTATE

CB-GETEDITSEL

CB-GETEXTENDEDUI

CB-GETITEMHEIGHT

CB-GETLBTEXT

CB-GETLBTEXTLEN

CB-INSERTSTRING

CB-LIMITTEXT

CB-RESETCONTENT

CB-SELECTSTRING

CB-SETCURSEL

CB-SETEDITSEL

CB-SETEXTENDEDUI

CB-SETITEMHEIGHT

CB-SHOWDROPDOWN

CBN-CLOSEUP

CBN-DBLCLK

CBN-DROPDOWN

CBN-EDITCHANGE

CBN-EDITUPDATE

CBN-ERRSPACE

CBN-KILLFOCUS

CBN-SELCHANGE

CBN-SELENDCANCEL

CBN-SELENDOK

CBN-SETFOCUS


Combo Box Messages See Also

Object-Manipulation Messages


Combo Box Notification Messages See Also

Event-Triggering Messages


D Functions

DELETEDC

DELETEMENU

DELETEOBJECT

DESTROYICON

DESTROYMENU

DESTROYWINDOW

DLGDIRLIST

DLGDIRLISTCOMBOBOX

DLGDIRSELECT or
DLGDIRSELECTEX

DLGDIRSELECTCOMBOBOX or
DLGDIRSELECTCOMBOBOXEX

DRAWMENUBAR


Edit Box Messages See Also

Object-Manipulation Messages


Edit Box Notification Messages See Also

Event-Triggering Messages


E-F Functions

ENABLEMENUITEM

ENABLEWINDOW

FINDWINDOW

FLASHWINDOW


E Messages

EM-CANUNDO

EM-EMPTYUNDOBUFFER

EM-FMTLINES

EM-GETFIRSTVISIBLELINE

EM-GETLINE

EM-GETLINECOUNT

EM-GETMODIFY

EM-GETPASSWORDCHAR

EM-GETRECT

EM-GETSEL

EM-LIMITTEXT

EM-LINEFROMCHAR

EM-LINEINDEX

EM-LINELENGTH

EM-LINESCROLL

EM-REPLACESEL

EM-SETMODIFY

EM-SETPASSWORDCHAR

EM-SETREADONLY

EM-SETRECT

EM-SETRECTNP

EM-SETSEL

EM-SETTABSTOPS

EM-UNDO

EN-CHANGE

EN-ERRSPACE

EN-HSCROLL

EN-KILLFOCUS

EN-MAXTEXT

EN-SETFOCUS

EN-UPDATE

EN-VSCROLL


Event-Triggering Messages See Also

Automatically-Processed Messages

Information-Only Messages

Object-Manipulation Messages


Functions Listed Alphabetically See Also

Messages Listed Alphabetically

Using Functions in WOW Extensions


G Functions

GETACTIVEWINDOW

GETASYNCKEYSTATE

GETCHARWIDTH

GETCLASSINFO

GETCLASSLONG

GETCLASSNAME

GETCLASSWORD

GETCLIENTADDR

GETCLIENTARGS

GETCLIENTRECT

GETCURRENTTASK

GETCURRENTTIME

GETCURSORPOS

GETDEVICECAPS

GETDIALOGBASEUNITS

GETDLGCTRLID

GETDLGITEM

GETDLGITEMINT

GETDLGITEMTEXT

GETDOSENVIRONMENT

GETDRIVETYPE

GETENVIRONMENTVARIABLE

GETFOCUS

GETINPUTSTATE

GETKEYBOARDSTATE

GETKEYBOARDTYPE

GETKEYNAMETEXT

GETKEYSTATE

GETMENU

GETMENUITEMCOUNT

GETMENUITEMID

GETMENUSTATE

GETMENUSTRING

GETNEARESTCOLOR

GETNEXTDLGGROUPITEM

GETNEXTDLGTABITEM

GETPARENT

GETPRIVATEPROFILEINT

GETPRIVATEPROFILESECTION

GETPRIVATEPROFILESTRING

GETPROFILEINT

GETPROFILESECTION

GETPROFILESTRING

GETSCROLLPOS

GETSCROLLRANGE

GETSTOCKOBJECT

GETSUBMENU

GETSYSCOLOR

GETSYSTEMDIRECTORY

GETSYSTEMMENU

GETSYSTEMMETRICS

GETTEMPFILENAME

GETTEMPPATH

GETTEXTMETRICS

GETTOPWINDOW

GETVERSION

GETVERSIONEX

GETWINDOW

GETWINDOWLONG

GETWINDOWRECT

GETWINDOWSDIRECTORY

GETWINDOWTEXT

GETWINDOWTEXTLENGTH

GETWINDOWWORD


Graphic Code Templates Tree in Designer

Code Templates Tree in the WOW Designer Window

In the WOW Designer window, the Code Templates tree displays a list of available templates (also called shortcuts) for a function call or a message and provides different ways of viewing this information. For example, selecting the Expand Tree command button expands the categorical grouping of functions and message shortcuts to include the individual functions and message shortcuts within each group, whereas selecting the Collapse Tree command button causes the list of functions and message shortcuts to collapse to the highest group in the tree. (You can also click the plus and minus signs to expand or collapse items in the hierarchical list.) When the Flat Tree check box is selected, all the available functions and message shortcuts are listed in alphabetical order.


H-I Functions

HILITEMENUITEM

HTMLHELP

INSERTMENU

ISCHARALPHA

ISCHARALPHANUMERIC

ISCHARLOWER

ISCHARUPPER

ISCHILD

ISDLGBUTTONCHECKED

ISICONIC

ISMENU

ISWINDOW

ISWINDOWENABLED

ISWINDOWVISIBLE

ISZOOMED


How Functions are Implemented See Also

Using Functions in WOW Extensions

Windows API Functions


How Messages are Interpreted See Also

How Messages are Implemented


Information-Only Messages See Also

Automatically-Processed Messages

Event-Triggering Messages

Object-Manipulation Messages


K-L Functions

KILLTIMER

LOCKWINDOWUPDATE


List Box Messages See Also

Object-Manipulation Messages


List Box Notification Messages See Also

Event-Triggering Messages


L Messages

LB-ADDSTRING

LB-DELETESTRING

LB-DIR

LB-FINDSTRING

LB-FINDSTRINGEXACT

LB-GETCARETINDEX

LB-GETCURSEL

LB-GETHORIZONTALEXTENT

LB-GETITEMHEIGHT

LB-GETITEMRECT

LB-GETSEL

LB-GETSELCOUNT

LB-GETSELITEMS

LB-GETTEXT

LB-GETTEXTLEN

LB-GETTOPINDEX

LB-INSERTSTRING

LB-RESETCONTENT

LB-SELECTSTRING

LB-SELITEMRANGE

LB-SETCARETINDEX

LB-SETCOLUMNWIDTH

LB-SETCURSEL

LB-SETHORIZONTALEXTENT

LB-SETITEMHEIGHT

LB-SETSEL

LB-SETTABSTOPS

LB-SETTOPINDEX

LBN-DBLCLK

LBN-ERRSPACE

LBN-KILLFOCUS

LBN-SELCANCEL

LBN-SELCHANGE

LBN-SETFOCUS


Messages Listed Alphabetically See Also

Functions Listed Alphabetically

Using Messages in WOW Extensions


M Functions

MESSAGEBEEP

MESSAGEBOX

MODIFYMENU

MOVEWINDOW


Object-Manipulation Messages See Also

Automatically-Processed Messages

Event-Triggering Messages

Information-Only Messages


O-P Functions

OEMTOANSI

OEMTOANSIBUFF

OPENICON

POSTMESSAGE


P Messages

PBM-DELTAPOS

PBM-SETPOS

PBM-SETRANGE32

PBM-SETSTEP

PBM-STEPIT


Popup Thin Client

WOW Thin Client provides the ability to execute WOW Extensions programs in a client/server architecture over a LAN or the Internet. All programs and data reside and execute on the server, but the Windows user interface is presented on a Windows workstation. This client/server implementation is carried out by integrating RPC (Remote Program Calls) technology with WOW Extensions.


Progress Bar Messages See Also

Object-Manipulation Messages


R Functions

REGISTERCLASS

RELEASECAPTURE

REMOTECOMMAND

REMOTECOPY

REMOTESHELLEXECUTE

REMOVEMENU


RPC Functions See Also

Using Functions in WOW Extensions

WOW Functions


Send Messages See Also

Object-Manipulation Messages


S Functions

SCREENTOCLIENT

SENDMESSAGE

SETACTIVEWINDOW

SETCAPTURE

SETCLASSLONG

SETCLASSWORD

SETCURSORPOS

SETDLGITEMINT

SETDLGITEMTEXT

SETENVIRONMENTVARIABLE

SETFOCUS

SETFOREGROUNDWINDOW

SETKEYBOARDSTATE

SETLOCALEMONETARY

SETLOCALENUMERIC

SETMENU

SETMENUITEMBITMAPS

SETPARENT

SETSCROLLPOS

SETSCROLLRANGE

SETTIMER

SETWINDOWLONG

SETWINDOWTEXT

SETWINDOWWORD

SHOWOWNEDPOPUPS

SHOWSCROLLBAR

SHOWWINDOW


Thin Client Functions See Also

Using Functions in WOW Extensions

WOW Functions


T-V Functions

TRACKPOPUPMENU

UNREGISTERCLASS

UPDATEWINDOW

VKKEYSCAN


Two Special WOW Functions See Also

Using Functions in WOW Extensions

WOW Functions


Using Functions in WOW Extensions See Also

Functions Listed Alphabetically

Using Messages in WOW Extensions


Using Literals as Function Parameters See Also

Using Functions in WOW Extensions

WOW Functions


Using Messages in WOW Extensions See Also

Messages Listed Alphabetically

Using Functions in WOW Extensions


W Functions

WINEXEC

WINHELP

WOWADDITEM

WOWADDMULTIPLESTRINGS

WOWCLEAR

WOWCLEARWAITCURSOR

WOWCREATEWINDOW

WOWDESTROYWINDOW

WOWDISCARDEVENTS

WOWENDMODAL

WOWFORMTOWOWVERSION

WOWGETCOBOLHWND

WOWGETFOCUS

WOWGETFONTS

WOWGETINDEXPROP

WOWGETMESSAGE

WOWGETNUM

WOWGETPROP

WOWGETWINDOWTYPE

WOWGLOBALMEMORYSTATUS

WOWINITALLCONTROLS

WOWINITCONTROL

WOWINPUTBOX

WOWLOADBITMAP

WOWLOADICON

WOWESSAGEBOX

WOWMOVE

WOWMULTICONTROLGETPROP

WOWMULTICONTROLSETPROP

WOWPEEKMESSAGE

WOWREFRESH

WOWREMOVEITEM

WOWRESETWAITCURSOR

WOWSETFOCUS

WOWSETINDEXPROP

WOWSETNEXTCTRL

WOWSETNUM

WOWSETPREVCTRL

WOWSETPROP

WOWSETSTRIPTRAILING

WOWSETWAITCURSOR

WOWSTARTMODAL

WOWTHINCLIENTREMOTEPROGRAM

WOWTHINCLIENTSETNOWAIT

WOWVERSION

WRITEPRIVATEPROFILESECTION

WRITEPRIVATEPROFILESTRING

WRITEPROFILESECTION

WRITEPROFILESTRING


Window and ActiveX Control Handle Parameters See Also

ActiveX Functions

Using Functions in WOW Extensions


Window Notification Messages See Also

Event-Triggering Messages


Windows API Functions See Also

Using Functions in WOW Extensions

WOW Functions


W Messages

WM-ACTIVATE

WM-ACTIVATEAPP

WM-CHAR

WM-CHARTOITEM

WM-CLEAR

WM-CLOSE

WM-COMMAND

WM-COMPACTING

WM-COPY

WM-CREATE

WM-CUT

WM-DEADCHAR

WM-DESTROY

WM-ENABLE

WM-FONTCHANGE

WM-GETFONT

WM-GETICON

WM-GETTEXT

WM-GETTEXTLENGTH

WM-HSCROLL

WM-KEYDOWN

WM-KEYUP

WM-KILLFOCUS

WM-LBUTTONDBLCLK

WM-LBUTTONDOWN

WM-LBUTTONUP

WM-MBUTTONDBLCLK

WM-MBUTTONDOWN

WM-MBUTTONUP

WM-MENUSELECT

WM-MOUSEACTIVATE

WM-MOVE

WM-NEXTDLGCTL

WM-PAINT

WM-PARENTNOTIFY

WM-PASTE

WM-POWER

WM-RBUTTONDBLCLK

WM-RBUTTONDOWN

WM-RBUTTONUP

WM-SETFOCUS

WM-SETFONT

WM-SETICON

WM-SETREDRAW

WM-SETTEXT

WM-SHOWWINDOW

WM-SIZE

WM-SPOOLERSTATUS

WM-SYSCHAR

WM-SYSCOLORCHANGE

WM-SYSCOMMAND

WM-SYSDEADCHAR

WM-SYSKEYDOWN

WM-SYSKEYUP

WM-TIMECHANGE

WM-TIMER

WM-UNDO

WM-VKEYTOITEM

WM-VSCROLL

WM-WINDOWPOSCHANGED

WM-WININICHANGE


WOW Functions See Also

ActiveX Functions

RPC Functions

Thin Client Functions

Using Functions in WOW Extensions