Describe user-friendly information about an instruction (action or condition), its parameters and the function name as well as other information for code generation. More...

#include <InstructionMetadata.h>

Inherits gd::AbstractFunctionMetadata.

Classes
class	ExtraInformation
	Defines information about how generate the code for an instruction. More...

Public Member Functions
	InstructionMetadata (const gd::String &extensionNamespace, const gd::String &name, const gd::String &fullname, const gd::String &description, const gd::String &sentence, const gd::String &group, const gd::String &icon, const gd::String &smallIcon)

	InstructionMetadata ()

const gd::String &	GetFullName () const

const gd::String &	GetDescription () const

const gd::String &	GetSentence () const

const gd::String &	GetGroup () const

ParameterMetadata &	GetParameter (size_t i)

const ParameterMetadata &	GetParameter (size_t i) const

size_t	GetParametersCount () const

const ParameterMetadataContainer &	GetParameters () const

const gd::String &	GetIconFilename () const

const gd::String &	GetSmallIconFilename () const

bool	CanHaveSubInstructions () const

const gd::String &	GetHelpPath () const

InstructionMetadata &	SetHelpPath (const gd::String &path)

bool	IsPrivate () const

InstructionMetadata &	SetPrivate () override

bool	IsRelevantForLayoutEvents () const

bool	IsRelevantForFunctionEvents () const

bool	IsRelevantForAsynchronousFunctionEvents () const

bool	IsRelevantForCustomObjectEvents () const

InstructionMetadata &	SetRelevantForLayoutEventsOnly () override

InstructionMetadata &	SetRelevantForFunctionEventsOnly () override

InstructionMetadata &	SetRelevantForAsynchronousFunctionEventsOnly () override

InstructionMetadata &	SetRelevantForCustomObjectEventsOnly () override

bool	IsAsync () const

bool	IsOptionallyAsync () const

InstructionMetadata &	SetCanHaveSubInstructions ()

InstructionMetadata &	SetHidden () override
	Set the instruction to be hidden in the IDE. More...

InstructionMetadata &	SetGroup (const gd::String &str)
	Set the group of the instruction in the IDE.

bool	IsHidden () const
	Return true if the instruction must be hidden in the IDE.

InstructionMetadata &	AddParameter (const gd::String &type, const gd::String &label, const gd::String &supplementaryInformation="", bool parameterIsOptional=false) override
	Add a parameter to the instruction metadata. More...

InstructionMetadata &	AddCodeOnlyParameter (const gd::String &type, const gd::String &supplementaryInformation) override
	Add a parameter not displayed in editor. More...

InstructionMetadata &	SetDefaultValue (const gd::String &defaultValue_) override
	Set the default value used in editor (or if an optional parameter is empty during code generation) for the last added parameter. More...

InstructionMetadata &	SetParameterLongDescription (const gd::String &longDescription) override
	Set the long description shown in the editor for the last added parameter. More...

InstructionMetadata &	SetParameterExtraInfo (const gd::String &extraInfo) override
	Set the additional information, used for some parameters with special type (for example, it can contains the type of object accepted by the parameter), for the last added parameter. More...

InstructionMetadata &	UseStandardOperatorParameters (const gd::String &type, const ParameterOptions &options)
	Add the default parameters for an instruction manipulating the specified type ("string", "number") with the default operators. More...

InstructionMetadata &	UseStandardRelationalOperatorParameters (const gd::String &type, const ParameterOptions &options)
	Add the default parameters for an instruction comparing the specified type ("string", "number") with the default relational operators. More...

InstructionMetadata &	SetIsObjectInstruction ()
	Mark the instruction as an object instruction. Automatically called when using `AddAction`/`AddCondition` on an `ObjectMetadata`.

InstructionMetadata &	SetIsBehaviorInstruction ()
	Mark the instruction as a behavior instruction. Automatically called when using `AddAction`/`AddCondition` on a `BehaviorMetadata`.

bool	IsObjectInstruction () const
	Check if the instruction is an object instruction.

bool	IsBehaviorInstruction () const
	Check if the instruction is a behavior instruction.

InstructionMetadata &	SetRequiresBaseObjectCapability (const gd::String &capability)
	Mark this (object) instruction as requiring the specified capability, offered by the base object. This is useful for some objects that don't support this capability, so that the editor can hide the instruction as it does not apply to them.

const gd::String &	GetRequiredBaseObjectCapability () const
	Get the required specified capability for this (object) instruction, or an empty string if there is nothing specific required.

InstructionMetadata &	MarkAsSimple ()
	Consider that the instruction is easy for a user to understand.

InstructionMetadata &	MarkAsAdvanced ()
	Consider that the instruction is harder for a user to understand than a normal instruction.

InstructionMetadata &	MarkAsComplex ()
	Consider that the instruction is complex for a user to understand.

int	GetUsageComplexity () const
	Return the usage complexity of this instruction for the user, from 0 (simple&easy to use) to 10 (complex to understand).

InstructionMetadata &	SetFunctionName (const gd::String &functionName_) override

InstructionMetadata &	SetAsyncFunctionName (const gd::String &functionName_)

const gd::String &	GetFunctionName ()

const gd::String &	GetAsyncFunctionName ()

InstructionMetadata &	SetManipulatedType (const gd::String &type_)
	Declare if the instruction being declared is somewhat manipulating in a standard way. More...

const gd::String &	GetManipulatedType () const
	Return the type manipulated in a standard way by the instruction. More...

InstructionMetadata &	SetGetter (const gd::String &getter)

InstructionMetadata &	SetMutators (const std::map< gd::String, gd::String > &mutators)

InstructionMetadata &	SetIncludeFile (const gd::String &includeFile) override
	Erase any existing include file and add the specified include. More...

InstructionMetadata &	AddIncludeFile (const gd::String &includeFile) override
	Add a file to the already existing include files.

const std::vector< gd::String > &	GetIncludeFiles () const override
	Get the files that must be included to use the instruction.

InstructionMetadata &	SetCustomCodeGenerator (std::function< gd::String(Instruction &instruction, gd::EventsCodeGenerator &codeGenerator, gd::EventsCodeGenerationContext &context)> codeGenerator)

InstructionMetadata &	RemoveCustomCodeGenerator ()

bool	HasCustomCodeGenerator () const

InstructionMetadata &	GetCodeExtraInformation ()
	Return the structure containing the information about code generation for the instruction. More...

Public Attributes
ExtraInformation	codeExtraInformation

ParameterMetadataContainer	parameters

Detailed Description

Describe user-friendly information about an instruction (action or condition), its parameters and the function name as well as other information for code generation.

Constructor & Destructor Documentation

◆ InstructionMetadata() [1/2]

gd::InstructionMetadata::InstructionMetadata	(	const gd::String &	extensionNamespace,
		const gd::String &	name,
		const gd::String &	fullname,
		const gd::String &	description,
		const gd::String &	sentence,
		const gd::String &	group,
		const gd::String &	icon,
		const gd::String &	smallIcon
	)

Construct a new instruction metadata.

◆ InstructionMetadata() [2/2]

gd::InstructionMetadata::InstructionMetadata ( )

Construct an empty InstructionMetadata.

Warning: Don't use this - only here to fullfil std::map requirements.

Member Function Documentation

◆ AddCodeOnlyParameter()

InstructionMetadata & gd::InstructionMetadata::AddCodeOnlyParameter	(	const gd::String &	type,
		const gd::String &	supplementaryInformation
	)

overridevirtual

Add a parameter not displayed in editor.

Parameters

type	One of the type handled by GDevelop. This will also determine the type of the argument used when calling the function in the generated code.
supplementaryInformation	Depends on `type`. For example, when `type == "inlineCode"`, the content of supplementaryInformation is inserted in the generated code.

See also: EventsCodeGenerator::GenerateParametersCodes

Implements gd::AbstractFunctionMetadata.

◆ AddParameter()

InstructionMetadata & gd::InstructionMetadata::AddParameter	(	const gd::String &	type,
		const gd::String &	label,
		const gd::String &	supplementaryInformation = `""`,
		bool	parameterIsOptional = `false`
	)

overridevirtual

Add a parameter to the instruction metadata.

Parameters

type	One of the type handled by GDevelop. This will also determine the type of the argument used when calling the function in the generated code.
description	Description for parameter
supplementaryInformation	Additional information that can be used for rendering or logic. For example: If type is "object", this argument will describe which objects are allowed. If this argument is empty, all objects are allowed. If type is "operator", this argument will be used to display only pertinent operators.
parameterIsOptional	true if the parameter must be optional, false otherwise.

See also: EventsCodeGenerator::GenerateParametersCodes

Implements gd::AbstractFunctionMetadata.

◆ GetAsyncFunctionName()

const gd::String& gd::InstructionMetadata::GetAsyncFunctionName ( )

inline

Return the name of the function, doing asynchronous work, which will be called in the generated code. This function should return an asynchronous task (i.e: gdjs.AsyncTask in the JavaScript runtime).

◆ GetCodeExtraInformation()

InstructionMetadata& gd::InstructionMetadata::GetCodeExtraInformation ( )

inline

Return the structure containing the information about code generation for the instruction.

Deprecated:

◆ GetFunctionName()

const gd::String& gd::InstructionMetadata::GetFunctionName ( )

inline

Return the name of the function which will be called in the generated code.

◆ GetHelpPath()

const gd::String& gd::InstructionMetadata::GetHelpPath ( ) const

inline

Get the help path of the instruction, relative to the GDevelop documentation root.

◆ GetManipulatedType()

const gd::String& gd::InstructionMetadata::GetManipulatedType ( ) const

inline

Return the type manipulated in a standard way by the instruction.

Parameters

type	"number" or "string"

◆ IsAsync()

bool gd::InstructionMetadata::IsAsync ( ) const

inline

Check if the instruction is asynchronous - it will be running in the background, executing the instructions following it before the frame after it resolved.

◆ IsOptionallyAsync()

bool gd::InstructionMetadata::IsOptionallyAsync ( ) const

inline

Check if the instruction asynchronicity is optional. If it is, it can either be used synchronously or asynchronously, with one function for each.

◆ IsPrivate()

bool gd::InstructionMetadata::IsPrivate ( ) const

inline

Check if the instruction is private - it can't be used outside of the object/ behavior that it is attached too.

◆ IsRelevantForAsynchronousFunctionEvents()

bool gd::InstructionMetadata::IsRelevantForAsynchronousFunctionEvents ( ) const

inline

Check if the instruction can be used in asynchronous function events.

◆ IsRelevantForCustomObjectEvents()

bool gd::InstructionMetadata::IsRelevantForCustomObjectEvents ( ) const

inline

Check if the instruction can be used in custom object events.

◆ IsRelevantForFunctionEvents()

bool gd::InstructionMetadata::IsRelevantForFunctionEvents ( ) const

inline

Check if the instruction can be used in function events.

◆ IsRelevantForLayoutEvents()

bool gd::InstructionMetadata::IsRelevantForLayoutEvents ( ) const

inline

Check if the instruction can be used in layouts or external events.

◆ SetAsyncFunctionName()

InstructionMetadata& gd::InstructionMetadata::SetAsyncFunctionName ( const gd::String & functionName_ )

inline

Set the name of the function, doing asynchronous work, which will be called in the generated code. This function should return an asynchronous task (i.e: gdjs.AsyncTask in the JavaScript runtime).

Parameters

functionName the name of the function doing asynchronous work to call.

◆ SetCanHaveSubInstructions()

InstructionMetadata& gd::InstructionMetadata::SetCanHaveSubInstructions ( )

inline

Notify that the instruction can have sub instructions.

◆ SetDefaultValue()

InstructionMetadata& gd::InstructionMetadata::SetDefaultValue ( const gd::String & defaultValue_ )

inlineoverridevirtual

Set the default value used in editor (or if an optional parameter is empty during code generation) for the last added parameter.

See also: AddParameter

Implements gd::AbstractFunctionMetadata.

◆ SetFunctionName()

InstructionMetadata& gd::InstructionMetadata::SetFunctionName ( const gd::String & functionName_ )

inlineoverridevirtual

Set the name of the function which will be called in the generated code.

Parameters

functionName the name of the function to call.

Implements gd::AbstractFunctionMetadata.

◆ SetGetter()

InstructionMetadata& gd::InstructionMetadata::SetGetter ( const gd::String & getter )

inline

If InstructionMetadata::ExtraInformation::SetManipulatedType was called with "number" or "string", this function will tell the code generator the name of the getter function used to retrieve the data value.

Usage example:

obj.AddAction("String",
               _("Change the string"),
               _("Change the string of a text"),
               _("the string"),
               _("Text"),
               "CppPlatform/Extensions/text24.png",
               "CppPlatform/Extensions/text_black.png");
 
    .AddParameter("object", _("Object"), "Text", false)
    .AddParameter("operator", _("Modification operator"), "string")
    .AddParameter("string", _("String"))
    .SetFunctionName("SetString").SetManipulatedType("string").SetGetter("GetString");
 
DECLARE_END_OBJECT_ACTION()

◆ SetHelpPath()

InstructionMetadata& gd::InstructionMetadata::SetHelpPath ( const gd::String & path )

inline

Set the help path of the instruction, relative to the GDevelop documentation root.

◆ SetHidden()

InstructionMetadata& gd::InstructionMetadata::SetHidden ( )

inlineoverridevirtual

Set the instruction to be hidden in the IDE.

Used mainly when an instruction is deprecated.

Implements gd::AbstractFunctionMetadata.

◆ SetIncludeFile()

InstructionMetadata& gd::InstructionMetadata::SetIncludeFile ( const gd::String & includeFile )

inlineoverridevirtual

Erase any existing include file and add the specified include.

Deprecated:: Use AddIncludeFile instead as clearing the list is more error prone.

Implements gd::AbstractFunctionMetadata.

◆ SetManipulatedType()

InstructionMetadata& gd::InstructionMetadata::SetManipulatedType ( const gd::String & type_ )

inline

Declare if the instruction being declared is somewhat manipulating in a standard way.

Parameters

type	"number" or "string"

◆ SetParameterExtraInfo()

InstructionMetadata& gd::InstructionMetadata::SetParameterExtraInfo ( const gd::String & extraInfo )

inlineoverridevirtual

Set the additional information, used for some parameters with special type (for example, it can contains the type of object accepted by the parameter), for the last added parameter.

See also: AddParameter

Implements gd::AbstractFunctionMetadata.

◆ SetParameterLongDescription()

InstructionMetadata& gd::InstructionMetadata::SetParameterLongDescription ( const gd::String & longDescription )

inlineoverridevirtual

Set the long description shown in the editor for the last added parameter.

See also: AddParameter

Implements gd::AbstractFunctionMetadata.

◆ SetPrivate()

InstructionMetadata& gd::InstructionMetadata::SetPrivate ( )

inlineoverridevirtual

Set that the instruction is private - it can't be used outside of the object/ behavior that it is attached too.

Implements gd::AbstractFunctionMetadata.

◆ SetRelevantForAsynchronousFunctionEventsOnly()

InstructionMetadata& gd::InstructionMetadata::SetRelevantForAsynchronousFunctionEventsOnly ( )

inlineoverridevirtual

Set that the instruction can be used in asynchronous function events.

Implements gd::AbstractFunctionMetadata.

◆ SetRelevantForCustomObjectEventsOnly()

InstructionMetadata& gd::InstructionMetadata::SetRelevantForCustomObjectEventsOnly ( )

inlineoverridevirtual

Set that the instruction can be used in custom object events.

Implements gd::AbstractFunctionMetadata.

◆ SetRelevantForFunctionEventsOnly()

InstructionMetadata& gd::InstructionMetadata::SetRelevantForFunctionEventsOnly ( )

inlineoverridevirtual

Set that the instruction can be used in function events.

Implements gd::AbstractFunctionMetadata.

◆ SetRelevantForLayoutEventsOnly()

InstructionMetadata& gd::InstructionMetadata::SetRelevantForLayoutEventsOnly ( )

inlineoverridevirtual

Set that the instruction can be used in layouts or external events.

Implements gd::AbstractFunctionMetadata.

◆ UseStandardOperatorParameters()

InstructionMetadata & gd::InstructionMetadata::UseStandardOperatorParameters	(	const gd::String &	type,
		const ParameterOptions &	options
	)

Add the default parameters for an instruction manipulating the specified type ("string", "number") with the default operators.

Note: The type "string" can be declined in several subtypes.

See also: ParameterMetadata

◆ UseStandardRelationalOperatorParameters()

InstructionMetadata & gd::InstructionMetadata::UseStandardRelationalOperatorParameters	(	const gd::String &	type,
		const ParameterOptions &	options
	)

Add the default parameters for an instruction comparing the specified type ("string", "number") with the default relational operators.

Note: The type "string" can be declined in several subtypes.

See also: ParameterMetadata

Member Data Documentation

◆ codeExtraInformation

ExtraInformation gd::InstructionMetadata::codeExtraInformation

Information about how generate code for the instruction

The documentation for this class was generated from the following files:

InstructionMetadata.h
InstructionMetadata.cpp

Classes

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ InstructionMetadata() [1/2]

◆ InstructionMetadata() [2/2]

Member Function Documentation

◆ AddCodeOnlyParameter()

◆ AddParameter()

◆ GetAsyncFunctionName()

◆ GetCodeExtraInformation()

◆ GetFunctionName()

◆ GetHelpPath()

◆ GetManipulatedType()

◆ IsAsync()

◆ IsOptionallyAsync()

◆ IsPrivate()

◆ IsRelevantForAsynchronousFunctionEvents()

◆ IsRelevantForCustomObjectEvents()

◆ IsRelevantForFunctionEvents()

◆ IsRelevantForLayoutEvents()

◆ SetAsyncFunctionName()

◆ SetCanHaveSubInstructions()

◆ SetDefaultValue()

◆ SetFunctionName()

◆ SetGetter()

◆ SetHelpPath()

◆ SetHidden()

◆ SetIncludeFile()

◆ SetManipulatedType()

◆ SetParameterExtraInfo()

◆ SetParameterLongDescription()

◆ SetPrivate()

◆ SetRelevantForAsynchronousFunctionEventsOnly()

◆ SetRelevantForCustomObjectEventsOnly()

◆ SetRelevantForFunctionEventsOnly()

◆ SetRelevantForLayoutEventsOnly()

◆ UseStandardOperatorParameters()

◆ UseStandardRelationalOperatorParameters()

Member Data Documentation

◆ codeExtraInformation