FREE PowerBuilder Training

Introduction to PowerBuilder

HomePrevious Lesson: Error Signaling
Next Lesson: Parameterized Events

Events and Messages

In MS-Windows operating system, event notification to applications is done by MS-Windows itself, by dispatching appropriate messages. Moving the mouse would be a simple example; when you move the mouse, MS-Windows sends WM_MOUSEMOVE message to the window in which the mouse pointer is located. This message has three parameters, cursor horizontal position( x co-ordinate ), vertical position ( y co-ordinate ) and a parameter that has flags which say which mouse button is down etc. Application respond to Windows by executing the code written for that event.

If the current window's application ( from the above example ) or infact any application ( in some messages ) doesn't  respond to the Windows message, MS-Windows takes default action depending on the message. In the above example, if you just move the mouse in "Program Manager", nothing happens. That is because, "Program Manager" which is a Windows application don't want to do anything when you simply move the mouse. To give you another example, MS-Word responds by displaying the toolbar help ( in yellow color ) when the mouse pointer is moved over the toolbar of MS-Word.

Look at another example, under Windows NT , which is more robust than MS-Windows, try shutting down the workstation when an application is executing something in a loop; What would happen? Since the application is busy executing code, it doesn't respond to operating system message "close yourself", so, Windows NT OS prompts saying if you would want to end the task. So, in the first example, Windows default action does nothing, where as the latter prompts the user.

All messages under Windows can be broadly divided into three categories: Informational, Notification and Action.

Message Type



Informational messages return the current state of on object. For example, whether an object or its foreground color is visible.


Notification messages inform objects that something has been done to the object. For example, when you click on a CommandButton, Windows tells the CommandButton 'You have been clicked' by sending an appropriate message.


Action messages do something to an object. For example, adding an entry in a ListBox or creating an object.

From MS-Windows application perspective, events in the application are triggered by MS-Windows messages. Applications respond to the MS-Windows message by executing the code written for that event. In simple terms, each event ( not every event, will be explained later ) in PowerBuilder is mapped onto one or other MS-Windows message. For the WM_MOUSEMOVE example explained earlier, PowerBuilder Window object has a "mousemove" event. This event is mapped to the WM_MOUSEMOVE message. In PowerBuilder, message id mapping has an extra layer. That is each Windows message is mapped to the same message id in PowerBuilder by replacing "WM" ( Windows Message ) with "PBM" ( PowerBuilder Message ) and is called "Event ID". Windows message WM_MOUSEMOVE is mapped to "pbm_mousemove" PowerBuilder Event ID. The event "mousemove" is in turn mapped to "pbm_mousemove".


 As said above, all most all Window messages are mapped to PowerBuilder Event Ids. PowerBuilder pre-defined some event names and mapped them to the event ids of each object. For example, a CommandButton has the following pre-defined events.

Event Name

Event Id























By looking at the above table you can see that mousemove event is not pre-defined for the CommandButton, but is pre-defined for the Window. Why didn't PowerBuilder define all event names for each object ? PowerBuilder pre-defined events that are most frequently used and required by the object . Want to display MircroHelp whenever a CommandButton gets focus, then  write script in the "GetFocus" ( PowerBuilder is case-insensitive ) as follows:

/* w_frame window is assumed as an MDI frame with microhelp window */
w_frame.SetMicroHelp( This.Tag )
/* PowerScript is explained in the later section. */

You may want to display floating help for buttons in the application ( like the one you see when you move the mouse pointer over the PowerBuilder toolbar ). In that case, writing code in "GetFocus" event wouldn't help, because, "GetFocus" event triggers only when the user tabs into the specified CommandButton or by calling SetFocus() in the PowerScript . What you really want is to display help whenever the mouse pointer moves over the CommandButton.

Just for this, PowerSoft made provision for defining events and mapping them to one of the available events. Events that you define are classified as "User Defined Events." You need to select "Declare/User Events" from the menu in the appropriate painter. The following picture displays the defining of  "ue_mousemove" event for a CommandButton by mapping it to the "pbm_mousemove" event id.

Provide a name under the "Event Name" and select one of the existing event ids from the "Paste Event Id" List Box ( Selecting Event ID is not mandatory, explained in a moment ).

An event id can be mapped to one event name at each object level. You can't unmap pre-defined events. If you don't want  anything to happen when an event occurs, then just don't write script for that event.

The following figure illustrates event classification and valid mappings.


We can divide PowerBuilder event ids into three categories.

Event Ids Category


Regular Window events

These event ids are mapped to Windows event ids. At each object level, some event ids are mapped to some event names. For example the Clicked event, which triggers automatically whenever the user clicks on a CommandButton.

Custom events

There are 75 custom events with event ids pbm_custom01 to pbm_custom75. When an user-defined event is defined and mapped to the custom event, the script doesn't execute it automatically - you need to explicitly execute the script. We'll look at them in detail latter in the chapter.

Visual Basic events

There are 50 Visual Basic events with event ids pbm_vbxevent01 to pbm_vbxevent50. These events are mapped from Visual Basic specific events.

Typically, VBXevents ( Visual Basic events ) are used for VBX user objects, to capture VBX events. With version 4.0, PowerBuilder supports OCX. Even Visual Basic v4.0 moved to OCXes. PowerBuilder automatically defines OCX events In the OLE control. We think, in the future versions, VBX events might not be supported, since every thing is achieved with OCXs. We will teach about OCX and OLE in later sessions.
HomePrevious Lesson: Error Signaling
Next Lesson: Parameterized Events

Copyright © 1996 - 2013 Prasad Bodepudi. All Rights Reserved.