Window events and functions ¶

Contents

Window events and functions
- Event function
- Event enable function

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:

EV_CREATE

The window has been created.

EV_DESTROY

The window has been destroyed.

EV_GAIN_FOCUS

The window has gained focus.

EV_LOSE_FOCUS

The window has lost focus.

EV_MINIMISED

The window has been minimised.

EV_MAXIMISED

The window has been maximised.

EV_RESTORE

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

EV_MOUSE_OVER

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

EV_RIGHT_MOUSE_UP

EV_RIGHT_MOUSE_DOWN

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.

event_enable = EV_DEFAULT | EV_RIGHT_MOUSE_UP

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)

EV_CHANGE

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:

EV_CHANGE_NO_WINDOW	The control for which EV_CHANGE was generated is not a window.
EV_CHANGE_NEW_SIZE	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.
EV_CHANGE_SIZING	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.
EV_CHANGE_END_SIZE	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.
EV_CHANGE_SCREEN_SIZE	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

EV_CLOSE

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.

EV_SELECT_TAB

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)

window_id	the identifier of the tab control window.
tab_id	the identifier of the tab control child window.
tab_id_xpos	the x co-ordinate of the tab control child window.

EV_SYSTEM_TRAY_ICON

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:

EV_SINGLE_CLICK	A single left click on the icon.
EV_DOUBLE_CLICK	A double left click on the icon.
EV_RIGHT_MOUSE_DOWN	Right mouse button down on the icon. Not generally used.
EV_RIGHT_MOUSE_UP	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.

EV_DRAG_ENTER
EV_DRAG_LEAVE
EV_DRAG_OVER
EV_DROP

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: