About user events
Windows, user objects, controls, menus and Application objects
each have a predefined set of events. In most cases, the predefined
events are all you need.
But there are times when you want to declare your own user
event. You can use predefined event IDs to trigger a
user event, or you can trigger it exclusively from within your application
scripts.
Here are some possible uses of user events:
- Keystroke processing You want to modify the way keystrokes are processed in your
application. For example, in a DataWindow control, you want the
user to be able to press down arrow and up
arrow to scroll among radio buttons in a DataWindow column
(normally, pressing these keys moves the focus to the next or preceding
row).
To do this, you define user events corresponding to Windows
events that PowerBuilder does not define. - Multiple methods You want to provide several ways to accomplish a certain task
within a window. For example, you want the user to be able to update
the database by either clicking a button or selecting a menu item. In
addition, you want to provide the option of updating the database
when the user closes the window.
To do this, you define a user event to update the database. - Communication between user object and
window You have placed a custom visual user object in a window and
need to communicate between the user object and the window.
For more information, see “Communicating between a
window and a user object “.
User events and eventIDs
An event ID connects events related to user actions or system
activity to a system message. PowerBuilder defines (or maps) events
to commonly used event IDs, and when it receives a system message,
it uses the mapped event ID to trigger an event. Some events, such
as those associated with PowerBuilder activity, are not mapped to
an event ID.
Event ID names
The PowerBuilder naming convention for user event IDs is similar
to the convention Windows uses to name messages. One or more Windows
messages maps to each PowerBuilder event ID.
| This Windows message | Maps to this event ID |
|---|---|
| wm_keydown | pbm_keydown |
| bm_getcheck (button class message) | pbm_bmgetcheck |
| bn_clicked (notification) | pbm_bnclicked |
See the Microsoft Windows Software Developer’s
Kit (SDK) documentation for more information about Windows messages.
PowerBuilder has its own events, each of which has an event
ID. For example, the PowerBuilder event DragDrop has the event ID
pbm_dragdrop. The event name and event ID of the predefined PowerBuilder events
are protected; they cannot be modified. The event IDs for predefined
events are shown in the Event List view:
About custom userevents
Obsolete technique Using custom user events is an obsolete PowerBuilder technique,
included for backward compatibility. If you do not want to map a
user event to a named pbm_ code, the recommended technique
is to use an unmapped user event.
For more information about using unmapped
events, see “Defining user events “.
Custom user events are mapped from the Windows wm_user
message numbers to pbm_customxx event
IDs. They are not meant to be used with standard controls such as
CommandButtons and DropDownListBoxes. They are meant to be used
only with DataWindow controls, windows, and user objects other than
standard visual user objects (which behave like the built-in controls
they inherit from).
Defining custom events for standard controls
Defining custom user events for standard controls is not recommended.
To define custom user events for standard controls, you must have
some Windows SDK experience and understand the following:
- All standard controls respond to standard events
in the range 0 to 1023. Most controls also define their own range
of custom events beyond 1023 (corresponding to wm_user
messages). - Some controls have custom events. You need to know
which controls do, because these custom events overlap with the PowerBuilder custom
events (pbm_customxx).
The pbm_custom01 event ID maps to wm_user+0,
pbm_custom02 maps to wm_user+1, and so
on, through pbm_custom75, which maps to wm_user+74. - You need to make sure that you use a pbm_custom
event ID that does not conflict with a custom event defined by Windows
for the standard control. Otherwise, you might encounter unexpected
behavior in your application.
For more information about Windows messages,
see the Microsoft Windows Software Developer’s Kit (SDK)
documentation.