AddUiFrameListener

ISettlers4Api::AddUiFrameListener method

Registers a frame listener whose callback will be called whenever a frame is about to be rendered. It can be used to add render code for the current frame (i.e. drawing overlays). The callback is only called if a specified ui element is visible to the player.

Use ISettlers4Api::AddFrameListener if you want a callback regardless of the currently visible elements.

Syntax

S4HOOK ISettlers4Api::AddUiFrameListener(
	LPS4FRAMECALLBACK lpCallback,
	S4_GUI_ENUM filter
);

Parameters

lpCallback

A function pointer to the callback function. This must not be NULL. See S4FrameProc for implementation details of this procedure.

filter

See ISettlers4Api::IsCurrentlyOnScreen for a complete list of values that you can specify in the filter parameter.

Return value

If the registration of the callback failed NULL is returned.

If the method succeeds it will returns a S4HOOK handle. Pass the S4HOOK to the ISettlers4Api::RemoveListener method to remove the callback from the chain when you do not need it anymore.

Remarks

All hooks must be removed with ISettlers4Api::RemoveListener before terminating the application.

When registering the callback is appended to the end of the callback chain, meaning that the callback will be processed on a first come first serve basis. If your callback is not called it may be due to another mod that consumes it and thus skips the subsequent callbacks.

Requirements

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

See also

S4FrameProc

ISettlers4Api

ISettlers4Api::RemoveListener

ISettlers4Api::AddFrameListener

ISettlers4Api::IsCurrentlyOnScreen