%U_WNDEVENTS

Associate methods with mouse events

WTSupported in traditional Synergy on Windows

 

 

 

return = %U_WNDEVENTS(subfunction[, arg, …])

or

xcall U_WNDEVENTS(subfunction[, arg, …])

Return value

return

On Windows, a value specific to the subfunction. On UNIX and OpenVMS, always returns false. (^VAL)

Arguments

subfunction

The function to perform: (n)

D_CREATE

Create a new method set.

D_ASSIGN

Assign a method set to one or more windows.

D_SIGNAL

Call a routine registered as part of a method set for a Toolkit window.

D_GETEVENT

Return the address of a method routine for a specified event.

D_GETEVENTS

Determine whether a method set has been registered for a Toolkit window and, if it has, return the method set ID.

arg

One or more arguments, depending on subfunction.

Discussion

%U_WNDEVENTS can be used to create an event method set, to assign an event method set to one or more windows for handling various mouse events, and to trigger a routine that is registered as part of a method set for a Toolkit window. See the individual subfunctions for details.

Note

Don’t use this function for event methods for ActiveX controls or for composite windows. Do the following instead:

  • For ActiveX controls, use the prefix argument for %AX_TKSINGLE and %GRID_CREATE to register extensions to the event method set that Toolkit automatically uses for these.
  • For composite windows, use the DC_EVENT subfunction for %C_CONTAINER to register extensions to the event method set that Toolkit automatically uses for these windows.

See also

Appendix D: Methods.

D_CREATE

method_set_id = %U_WNDEVENTS(D_CREATE, [elb], event, event_method, 
&           [event, event_method][, …])

or

xcall U_WNDEVENTS(D_CREATE, [elb], event, event_method, [event, event_method][, …])

Return value

method_set_id

A method set ID if successful, or false (0) if not. (^VAL)

Arguments

elb

(optional) The name of the library from which to draw the event_method routines. (a)

event

The ID of the event: (n)

D_EVENT_LEFT_CLICK = Left mouse button event.

D_EVENT_MIDDLE_CLICK = Middle mouse button event.

D_EVENT_RIGHT_CLICK = Right mouse button event.

D_EVENT_LEFT_DBLCLK = Double‑click left mouse button.

D_EVENT_MIDDLE_DBLCLK = Double‑click middle mouse button.

D_EVENT_RIGHT_DBLCLK = Double‑click right mouse button.

D_EVENT_MOVE = Move window event.

D_EVENT_SIZE = Size window event.

D_EVENT_MINIMIZE = Minimize window event.

D_EVENT_MAXIMIZE = Maximize window event.

D_EVENT_RESTORE = Restore window event.

D_EVENT_SCROLL = Scroll window event.

D_EVENT_CLOSE = Close window event.

event_method

The name of the %UWNDEVENTS_METHOD function that will handle the event. (a)

Discussion

The D_CREATE subfunction of %U_WNDEVENTS is used to define which %UWNDEVENTS_METHOD should be invoked for a specific event. You can specify the same %UWNDEVENTS_METHOD for more than one event, or for all events.

Event and event_method must be specified as a pair. You can specify more than one event pair to %U_WNDEVENTS. All event pairs specified within one D_CREATE call to %U_WNDEVENTS are referred to as a method set and will be identified by a method set ID, which is returned by this function.

Only the events specified in the method set will invoke a call to %UWNDEVENTS_METHOD. The method set must also be associated with a window. See D_ASSIGN for information on associating methods with windows.

Important

Once defined, method sets continue to exist for the life of your program. Each method set requires a small amount of memory. Be careful to avoid creating more method sets than you need, and try to reuse each method set for multiple windows. Creating too many method sets could result in performance degradation or program termination.

If D_EVENT_SIZE is specified, the frame of the window is changed to one that the user can “grab” by clicking and dragging the border to designate the new size. Also, a “Size” menu entry is placed on the window’s system menu to allow for the use of the keyboard when resizing. If this method is removed from the window, its corresponding menu entry is also removed. Argument_5 and argument_6 refer to the width and height of the logical window. The logical window is defined as the rows and columns used by Synergy/DE. Argument_7 and argument_8 refer to the width and height of the client area. The client area is defined as the visible area within the window (inside the frame and scroll bars) in which client objects can be placed.

Resizing is snapped to the nearest row/column boundary. A window can be resized no smaller than the minimum size required for buttons plus one row and column of window space. When a window is resized, the display area of the window is modified, rather than the actual window size. If the window has a display area smaller than the total window area and scroll bars are enabled, scroll bars are displayed. When the scroll bars are moved, the display area origin changes. If scroll bars are disabled, they are not displayed. In certain instances, scroll bars may not be desirable, such as when the resizable window contains only one resizable component that shows scroll bars. Scroll bars are enabled and disabled using the WB_SBON and WB_SBOFF subfunctions of W_BRDR.

When a tab set container is resized smaller, the tabbed dialogs inside the container are also resized. If a window on a tab is resizable and scroll bars have not been disabled for that window, then scroll bars will be shown on the contained window if the tab is no longer large enough to display the entire window. Because the border of a contained window is turned off when it is placed on a tab, you must assign the window method set (with D_ASSIGN) prior to placing the window in the tab set. If a contained window does not show scroll bars (either because it is not resizable or because scroll bars have been disabled with W_BRDR), then resizing the tab set smaller may clip the contained window so that it cannot all be viewed by the user. If a tab set container is sized larger than its logical window size, the tab set is still only as large as the logical window size.

For a list, horizontal resizing is limited to between 1 and the number of columns in the associated input window, and vertical resizing is limited at 1 and has no logical upper limit.

With the “full drag mode” enabled in Windows, resize events may occur rapidly. Therefore, actions performed in the resize method should be minimal and quick, otherwise the message queue may fill up.

If D_EVENT_MINIMIZE is specified, a minimize button is added to the right side of the window’s frame, as well as a “Minimize” menu entry on the window’s system menu. A “Restore” menu entry is also added. The minimize button changes to a restore button when the window is minimized. A %UWNDEVENTS_METHOD must be written to enable this functionality; however, the method need not actually do anything. If this method is removed from the window, its corresponding button and menu entry are also removed.

When a window is minimized, a minimal title bar is displayed along the bottom border of the application window. The display area of a minimized window remains unaffected.

If D_EVENT_MAXIMIZE is specified, a maximize button is added to the right side of the window’s frame, as well as a “Maximize” menu entry on the window’s system menu. A “Restore” menu entry is also added. The maximize button changes to a restore button when the window is maximized. A %UWNDEVENTS_METHOD must be written to enable this functionality; however, the method need not actually do anything. If this method is removed from the window, its corresponding button and menu entry are also removed.

When a maximize event occurs, a resize event also occurs so that the application can respond to the change in size.

If a window is maximized, the display area is set to the number of visible rows and columns, or the maximum number of rows and columns, whichever is smaller. The frame of the window occupies the entire desktop, even if part of the contained area lies outside of the window’s logical size. In this case, the excess area is painted with the application background color defined by Windows.

When a window is restored, the display area is set to the number of rows and columns that fit into the restored rectangle. Note that when a restore event occurs, a resize event also occurs so that the application can respond to the change in size.

The D_EVENT_MOVE, D_EVENT_SIZE, D_EVENT_MINIMIZE, D_EVENT_MAXIMIZE, D_EVENT_RESTORE, D_EVENT_SCROLL, and D_EVENT_CLOSE events occur in response to both user action and programmatic changes to the window. For instance, a window can be programmatically maximized, minimized, or restored even if it doesn’t have a corresponding method, by using the W_PROC(WP_STATE) subroutine. The application should not assume that an event is always fired in response to a user’s action. For instance, if a resize method resizes the window, an infinite loop of method invocation can occur.   

Note

Selection windows do not support the minimize, maximize, or restore buttons, and they don’t support the sizing arrow you see when you drag the edge or corner of a window. Because of this, users aren’t able to minimize, maximize, restore, or size selection windows. However, you can do these things programmatically by using W_PROC. If you use W_PROC, events associated with the selection window will be called.

D_ASSIGN

status = %U_WNDEVENTS(D_ASSIGN, method_set_id, window_id[, …])

or

xcall U_WNDEVENTS(D_ASSIGN, method_set_id, window_id[, …])

Return value

status

True or false depending upon success of the assignment. (^VAL)

Arguments

method_set_id

The method set ID returned from the D_CREATE subfunction. (n)

window_id

The window ID that will produce those events. (n)

Discussion

The method set ID obtained from the D_CREATE subfunction of %U_WNDEVENTS must be associated with at least one window before the methods associated with mouse events are ever called. The D_ASSIGN subfunction associates the method set ID with one or more windows.

If you have at least one method set created, you can start handling mouse events specified in the method set by associating the method set ID with windows. The same method set may be associated with one or more windows in your Synergy application. Or, you could define and assign a different method set to each window.

Once you associate your application windows with a method set ID, event methods will start receiving calls as mouse events occur.

Only one method set may be assigned to a window; therefore if you call %U_WNDEVENTS with the D_ASSIGN subfunction more than once for the same window, the last method set assigned is the one that will be retained. Any previous one will be ignored.

%U_WNDEVENTS cannot be used to associate method sets with lists. To associate a method set with a list, use the D_LWNDEVENT function in L_METHOD.

D_SIGNAL

rval = %U_WNDEVENTS(D_SIGNAL, window_id, event[, arg, …])

or

xcall U_WNDEVENTS(D_SIGNAL, window_id, event[, arg, …])

Return value

rval

The value returned by the triggered event routine. (^VAL)

Arguments

window_id

The ID of the Toolkit window whose method set contains the routine you want to trigger. (n)

event

The %UWNDEVENTS_METHOD event code for the routine to be triggered. (n)

arg

(optional) One or more arguments required for the routine. (n)

Discussion

The D_SIGNAL subfunction of %U_WNDEVENTS triggers a routine that is registered as part of a method set for a Toolkit window. You specify the routine by passing the %UWNDEVENTS_METHOD event code for the routine as the event argument. For example, to trigger the D_EVENT_SIZE method for a window, pass D_EVENT_SIZE as event. Note that if no method is registered for the window for the specified event, the signal is ignored. For a list of these method codes (which are defined in tools.def), see %UWNDEVENTS_METHOD.

D_GETEVENT

method_addr = %U_WNDEVENTS(D_GETEVENT, method_set, event)

Return value

method_addr

The address (D_ADDR) for the method for the event passed as event, or 0 if no routine is registered for this event. (^VAL)

Arguments

method_set

The method set ID. (n)

event

The event code for the routine whose address you want to retrieve. (n)

Discussion

The D_GETEVENT subfunction of %U_WNDEVENTS enables you to determine if a method is registered for a given event in a method set and, if so, what the address for the method routine is. For example, the following returns the address of the method for D_EVENT_LEFT_CLICK, or it returns 0 if no method is registered for D_EVENT_LEFT_CLICK. (Note how D_GETEVENTS enables us to use the window ID to get this information.)

method_address=%u_wndevents(D_GETEVENT, %u_wndevents(D_GETEVENTS, wndid),
 &             D_EVENT_LEFT_CLICK)

For a list of the method codes you can pass as event, see %UWNDEVENTS_METHOD.

D_GETEVENTS

method_set = %U_WNDEVENTS(D_GETEVENTS, window_id)

Return value

method_set

The method set ID, or 0 if there is no method set associated with the specified window. (^VAL)

Arguments

window_id

The ID of the window whose method set ID you want to retrieve. (n)

Discussion

The D_GETEVENTS subfunction of %U_WNDEVENTS enables you to determine if a method set has been registered for a UI Toolkit window and, if it has, what the ID for the method set is.