CustomMsgHandle

Macros and types used for working with the handles for custom messages. More...

Macros
#define	EZTR_CUSTOM_MSG_HANDLE_NAME(name_suffix)
	Uses to set/get the actual symbol name for custom message handles If you want to add a prefix/suffix to your custom message handles globally, it can be done here.
#define	EZTR_DEFINE_CUSTOM_MSG_HANDLE_NO_EXPORT(name)
	Creates a non-exported CustomMsgHandle object.
#define	EZTR_DEFINE_CUSTOM_MSG_HANDLE(name)
	Creates a CustomMsgHandle object.
#define	EZTR_DECLARE_CUSTOM_MSG_HANDLE(name)
	Creates a declaration for a CustomMsgHandle object.
#define	EZTR_EXTERN_CUSTOM_MSG_HANDLE(name)
	Creates a declaration for a CustomMsgHandle object. Alternative to EZTR_DECLARE_CUSTOM_MSG_HANDLE.
#define	EZTR_IMPORT_CUSTOM_MSG_HANDLE(mod_str, name_suffix)
	Declares and imports a CustomMsgHandle object from another mod.
#define	EZTR_IMPORT_CUSTOM_MSG_HANDLE_NO_PREFIX(mod_str, name)
	Declares and imports a CustomMsgHandle object from another mod.
#define	EZTR_GET_CUSTOM_MSG_ID(handle)
	Gets the textId from a custom message handle.
#define	EZTR_HNAME(name_suffix)
	Shorthand for EZTR_CUSTOM_MSG_HANDLE_NAME()
#define	EZTR_GET_ID(handle)
	Gets the textId from a custom message handle.
#define	EZTR_GET_ID_H(handle)
	Gets the textId from a custom message handle.

Detailed Description

Macros and types used for working with the handles for custom messages.

This page contains all of the information in custom message handles an how to use them.

It's worth noting that a custom message handle is actually a function, defined through macros. In brief, here are the important things to know:

• The handler's only argument is a pointer that EZTR uses internally. Modders don't need to use it.
• You can retrieve the handle's textId by calling it with NULL as the argument (handle(NULL))
• By default, the handle can only have its textId assigned once (See below on how to change this behavior).
• Handles created using EZTR_DEFINE_CUSTOM_MSG_HANDLE, the recommended macro for creating custom message handles, are marked with RECOMP_EXPORT.

This implementation was decided on to ensure that the textIds of custom messages are not lost through variable reassignments, and to facilitate mods potentially needing to access/modify each other's messages.

For those interested in the technical details: The function's only argument is used by EZTR to set the textId variable when a custom message is assigned to it, and to check that the assignment was a success.

The version of the handle function included in this header stores the textId in a static variable, and includes logic that will only allow the textId to be set once. If a second attempt to set the ID is made, an error message is printed. Rather than change a handle's textId, you should change the stored message at that id.

If you want to change the behavior of the handles, you can write your own custom message handle functions, but it's not recommended.

Macro Definition Documentation

EZTR_CUSTOM_MSG_HANDLE_NAME

#define EZTR_CUSTOM_MSG_HANDLE_NAME

(

name_suffix

)

Value:

EZTR_CustomMsgHandle_##name_suffix

Uses to set/get the actual symbol name for custom message handles If you want to add a prefix/suffix to your custom message handles globally, it can be done here.

EZTR_DECLARE_CUSTOM_MSG_HANDLE

#define EZTR_DECLARE_CUSTOM_MSG_HANDLE

(

name

)

Value:

u16 EZTR_CUSTOM_MSG_HANDLE_NAME(name)(_EZTR_CustomMsgHandleSetter* setter)

Creates a declaration for a CustomMsgHandle object.

Use this reference handles created in other .c files. Also works in headers.

EZTR_DEFINE_CUSTOM_MSG_HANDLE

#define EZTR_DEFINE_CUSTOM_MSG_HANDLE

(

name

)

Value:

RECOMP_EXPORT \
u16 EZTR_CUSTOM_MSG_HANDLE_NAME(name)(_EZTR_CustomMsgHandleSetter* setter) \
__EZTR_CUSTOM_MSG_HANDLE_BODY(name)

Creates a CustomMsgHandle object.

This is the primary method for creating handles for custom messages. You'll need to use this macro inside one of your .c files (outside of any functions) to create the handle itself. Use EZTR_DECLARE_CUSTOM_MSG_HANDLE to access the handle from other files.

See the EZTR_CustomMsgHandle documentation for more information about handles and how they work.

EZTR_DEFINE_CUSTOM_MSG_HANDLE_NO_EXPORT

#define EZTR_DEFINE_CUSTOM_MSG_HANDLE_NO_EXPORT

(

name

)

Value:

u16 EZTR_CUSTOM_MSG_HANDLE_NAME(name)(_EZTR_CustomMsgHandleSetter* setter) \
__EZTR_CUSTOM_MSG_HANDLE_BODY(name)

Creates a non-exported CustomMsgHandle object.

Most mods are not installed in a vacuum. You should consider exporting your custom message handles so that other mods can access the messages you define if need be (compatibility patches, addons, etc.)

EZTR_EXTERN_CUSTOM_MSG_HANDLE

#define EZTR_EXTERN_CUSTOM_MSG_HANDLE

(

name

)

Value:

EZTR_DECLARE_CUSTOM_MSG_HANDLE(name)

Creates a declaration for a CustomMsgHandle object. Alternative to EZTR_DECLARE_CUSTOM_MSG_HANDLE.

Use this reference handles created in other .c files. Also works in headers.

EZTR_GET_CUSTOM_MSG_ID

#define EZTR_GET_CUSTOM_MSG_ID

(

handle

)

Value:

handle(NULL)

Gets the textId from a custom message handle.

A more readable alternative to handle(NULL)

EZTR_GET_ID

#define EZTR_GET_ID

(

handle

)

Value:

EZTR_GET_CUSTOM_MSG_ID(handle)

Gets the textId from a custom message handle.

A more readable alternative to handle(NULL), and shorthand for EZTR_GET_CUSTOM_MSG_ID()

Note that this macro won't apply the global prefix if it's enabled. You'll need to use something like EZTR_GET_CUSTOM_MSG_ID(EZTR_HNAME(my_handle)) or EZTR_GET_ID(EZTR_HNAME(my_handle)).

EZTR_GET_ID_H

#define EZTR_GET_ID_H

(

handle

)

Value:

EZTR_GET_CUSTOM_MSG_ID(EZTR_CUSTOM_MSG_HANDLE_NAME(handle))

Gets the textId from a custom message handle.

A more readable alternative to EZTR_CustomMsgHandle_##handle(NULL).

This macro WILL apply the global prefix if it's enabled, and can be considered shorthand for EZTR_GET_CUSTOM_MSG_ID(EZTR_HNAME(my_handle)) or EZTR_GET_ID(EZTR_HNAME(my_handle)).

EZTR_HNAME

#define EZTR_HNAME

(

name_suffix

)

Value:

EZTR_CUSTOM_MSG_HANDLE_NAME(name_suffix)

Shorthand for EZTR_CUSTOM_MSG_HANDLE_NAME()

Useful if you want to use global prefixes.

EZTR_IMPORT_CUSTOM_MSG_HANDLE

#define EZTR_IMPORT_CUSTOM_MSG_HANDLE	(		mod_str,
			name_suffix )

Value:

RECOMP_IMPORT(mod_str, u16 EZTR_CustomMsgHandle_##name_suffix(_EZTR_CustomMsgHandleSetter* setter))

Declares and imports a CustomMsgHandle object from another mod.

This will allow you to use and interact with custom messages from other mods.

EZTR_IMPORT_CUSTOM_MSG_HANDLE_NO_PREFIX

#define EZTR_IMPORT_CUSTOM_MSG_HANDLE_NO_PREFIX	(		mod_str,
			name )

Value:

RECOMP_IMPORT(mod_str, u16 name(_EZTR_CustomMsgHandleSetter* setter))

Declares and imports a CustomMsgHandle object from another mod.

This will allow you to use and interact with custom messages from other mods.