set_message_paramT_set_message_paramSetMessageParamSetMessageParamset_message_param (Operator)
Name
set_message_paramT_set_message_paramSetMessageParamSetMessageParamset_message_param — Set message parameter or invoke commands on the message.
Signature
void SetMessageParam(const HTuple& MessageHandle, const HTuple& GenParamName, const HTuple& Key, const HTuple& GenParamValue)
void HMessage::SetMessageParam(const HString& GenParamName, const HTuple& Key, const HTuple& GenParamValue) const
void HMessage::SetMessageParam(const HString& GenParamName, const HString& Key, const HTuple& GenParamValue) const
void HMessage::SetMessageParam(const char* GenParamName, const char* Key, const HTuple& GenParamValue) const
void HMessage::SetMessageParam(const wchar_t* GenParamName, const wchar_t* Key, const HTuple& GenParamValue) const
(Windows only)
Description
set_message_paramset_message_paramSetMessageParamSetMessageParamSetMessageParamset_message_param sets message
parameters or invokes action commands on the message.
For each call of set_message_paramset_message_paramSetMessageParamSetMessageParamSetMessageParamset_message_param, only a single parameter can be
set. However, there are two types of parameters/commands:
-
Parameters/commands applicable to the entire message. In this case
no keys must be specified, i.e., the parameter KeyKeyKeyKeykeykey must be an empty
tuple.
-
Parameters/commands applicable to the individual keys. In this case a
non-empty list of keys must be specified in parameter KeyKeyKeyKeykeykey. The
keys are processed in the same order as specified in the KeyKeyKeyKeykeykey
parameter.
Key-independent parameter names:
- 'remove_all_keys'"remove_all_keys""remove_all_keys""remove_all_keys""remove_all_keys""remove_all_keys":
Removes all the keys currently stored in the message and releases
all the (control or iconic) data associated with those keys.
The operation results in an empty message.
Note that contents of GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value is ignored for this
parameter, while KeyKeyKeyKeykeykey must be an empty tuple.
Key-specific parameter names:
- 'remove_key'"remove_key""remove_key""remove_key""remove_key""remove_key":
Removes the keys specified in the KeyKeyKeyKeykeykey parameter and releases
all the (tuple or object) data associated with those keys.
If an error occurs while processing one or more keys (in particular
if the key is invalid), the operator attempts to continue removing
as many keys as possible before reporting the failure.
Note that the contents of GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value is ignored for this
parameter.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
This operator modifies the state of the following input parameter:
During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.
Parameters
MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle (input_control, state is modified) message → HMessage, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Message handle.
Number of elements: MessageHandle == 1
Restriction: MessageHandle != 0
GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Names of the message parameters or action commands.
Number of elements: GenParamName == 1
Default value:
'remove_key'
"remove_key"
"remove_key"
"remove_key"
"remove_key"
"remove_key"
List of values: 'remove_all_keys'"remove_all_keys""remove_all_keys""remove_all_keys""remove_all_keys""remove_all_keys", 'remove_key'"remove_key""remove_key""remove_key""remove_key""remove_key"
KeyKeyKeyKeykeykey (input_control) string(-array) → HTupleMaybeSequence[Union[str, int]]HTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)
Message keys the parameter/command should be applied to.
GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) tuple(-array) → HTupleMaybeSequence[Union[int, float, str]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)
Values of the message parameters or action commands.
Example (HDevelop)
* Remove some keys
set_message_param (Message, 'remove_key', ['my_image', 'simple_string'], [])
Result
If all the operator parameters, and their values, as well as specified
keys are valid, set_message_paramset_message_paramSetMessageParamSetMessageParamSetMessageParamset_message_param returns 2 (H_MSG_TRUE).
Otherwise an exception is raised.
Possible Predecessors
dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message,
create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message
Possible Successors
enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message,
clear_messageclear_messageClearMessageClearMessageClearMessageclear_message
See also
create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message,
clear_messageclear_messageClearMessageClearMessageClearMessageclear_message,
set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple,
get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple,
set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj,
get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj,
get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param,
enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message,
dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message
Module
Foundation