Window events and functions

Event function

event = func_id

The name of the function to be called when an event occurs in this window.

The function is called as follows:

func_id(event_code, window_id)

Certain events send additional arguments.

The events which cause the function to be called are:


The window has been created.


The window has been destroyed.


The window has gained focus.


The window has lost focus.


The window has been minimised.


The window has been maximised.


The window has been restored from a maximised size to its default size.


The user has moved the mouse over the window during a dialog.

The user has clicked down or released the right mouse button within the window or the program’s system tray icon (but not over a control).

Note that this event is not a default event and must be enabled, e.g.


See the event_enable clause.

A common use for EV_RIGHT_MOUSE_UP is to open a popup menu.The event sends extra arguments to the event function indicating the position of the click:

func_id (EV_RIGHT_MOUSE_UP, window_id, xpos, ypos)


The user has resized the window. The event sends extra arguments to the event function:

func_id (EV_CHANGE, window_id, old_width, old_height, event_detail)

The new width and height can be retrieved from the view_width and view_height properties, e.g.

tmp.CurrentWidth = wintask->view_width

The event_detail argument describes the resize event in more detail. Possible values for event_detail are:


The control for which EV_CHANGE was generated is not a window.


The window has been resized and “Show window contents while dragging” is checked in the user’s display effects. This is an interim event. It provides the option to show new content in the window even though the user is still resizing the window. This event is not sent if “Show window contents while dragging” is unchecked. If the programmer needs to scroll a window that is being resized, this must be done in the EV_CHANGE_SIZING event and/or the EV_CHANGE_END_SIZE event. The window must not be scrolled during its EV_CHANGE_NEW_SIZE event.


The window has been resized. This is an interim event that is sent whether or not “Show window contents while dragging” is checked. The user is still dragging the window border.


The window has been resized and the user has released the left mouse button. This event is sent whether or not “Show window contents while dragging” is checked.


The screen size has changed (e.g. from portait to landscape).

Note that EV_CHANGE is not a default event and must be enabled:.

event_enable = EV_DEFAULT | EV_CHANGE


The user has clicked on the window’s close icon. It is the programmer’s responsibility to accept the request, and then to close or destroy the window, as appropriate for the application, or to refuse the request. Unless the window has the style flag WS_HOTWINDOW assigned, EV_CLOSE is only generated during a dialog.

If the user clicks a window’s close button while a textbox has focus and the EV_CLOSE event function causes the program to exit, then by default any value typed into the textbox is not saved. This allows a program to be closed even though invalid data has been typed into the textbox. If the program requires the value to be saved, subject to validation, the event function can execute the save_text command.


This event is generated when a tab in a tab control window is selected. Note that the event function must be assigned to the tab control window; it need not be assigned to the tab control child windows. EV_GAIN_FOCUS is not used because it is the tab control window that receives focus, not the tab itself. See Tab control windows.

This event sends extra arguments to the event function:

func_id (EV_SELECT_TAB, window_id, tab_id, tab_id_xpos)


the identifier of the tab control window.


the identifier of the tab control child window.


the x co-ordinate of the tab control child window.


This event is generated by mouse clicks on the program’s system tray icon. The system_tray_icon() function is used to create and manage the system tray icon. The event is tested in combination with the mouse click event, in order to distinguish from the same mouse event in the window. The following events can be tested with EV_SYSTEM_TRAY_ICON:


A single left click on the icon.


A double left click on the icon.


Right mouse button down on the icon. Not generally used.


Right mouse button up on the icon. This is the preferred event for responding to right mouse clicks. A likely use is to open a popup menu.


These drag and drop events can only be generated for a window with the style flag WS_DROP_TARGET. See Using drag and drop.

If drag and drop events are required, they must be enabled in the target window by means of the event_enable clause. Enabling EV_DRAG_DROP enables all drag and drop events. The following example enables drag and drop in addition to those events enabled for a window by default:

event_enable = EV_DEFAULT | EV_DRAG_DROP

New events may be added in the future. See Event functions.

Event enable function

event_enable = flags

This clause is used to select the event codes which are to be enabled for the window.

Default: The standard set of events listed under the event = clause above.

See The event_enable clause.