S4MouseProc

S4MouseProc callback function

An application-defined or library-defined callback function used with the ISettlers4Api::AddMouseListener method. The library calls this function whenever the user is triggering mouse buttons or the mouse wheel. It can be used to add new behavior to custom drawn overlays.

The LPS4MOUSECALLBACK type defines a pointer to this callback function.

Syntax

HRESULT S4HCALL S4MouseProc(
	DWORD dwMouseButton, 
	INT iX, 
	INT iY, 
	DWORD dwMsgId, 
	HWND hwnd, 
	LPCS4UIELEMENT lpUiElement
);

Parameters

dwMouseButton

Indicates whether various keys are down. See wParam of the various mouse messages like WM_LBUTTONDOWN.

This also contains the wheel delta in case a mouse wheel message (WM_MOUSEHWHEEL) is beeing received. Use the GET_WHEEL_DELTA_WPARAM macro to retrieve the wheel delta from the dwMouseButtons param.

The dwMouseButtons parameter can be one or more of the following values.

Value	Meaning
MK_CONTROL 0x0008	The CTRL key is down.
MK_LBUTTON 0x0001	The left mouse button is down.
MK_MBUTTON 0x0010	The middle mouse button is down.
MK_RBUTTON 0x0002	The right mouse button is down.
MK_SHIFT 0x0004	The SHIFT key is down.
MK_XBUTTON1 0x0020	The first X button is down.
MK_XBUTTON2 0x0040	The second X button is down.

iX

The x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

iY

The y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

dwMsgId

The message id that is being processed. It is for example WM_LBUTTONDOWN, WM_MOUSEHWHEEL, etc. Here is a complete list: https://docs.microsoft.com/en-us/windows/win32/inputdev/mouse-input-notifications.

Note that the dwMouseButtons, iX and iY parameter depend on the message id. Always check the window messages when processing these parameters.

hwnd

A handle to the window.

lpUiElement

A pointer to a S4UiElement struct. This struct contains data for the ui element of the game that the cursor is currently hovering over. It will be NULL if the cursor is not hovering over any ui element.

Return value

If the event is being consumed and you do not want to propagate it you must return 1.

If the event was not consumed return 0. The library will then try to pass it to the next callback in the chain or to the game if the chain has been processed.

Remarks

Note that not even the game gets to process the event if you return 1. Other callbacks in the chain are skipped and will not get a chance to process this event.

Requirements

Minimum API Level	1
Target Edition	Any
Header	S4ModApi.h
Library	S4ModApi.lib
DLL	S4ModApi.dll

See also

ISettlers4Api

ISettlers4Api::AddMouseListener