NAME
- InvertString
-
produce input events that would generate the given string. (V36)
SYNOPSIS
events = InvertString(str,km)
struct InputEvent *InvertString(STRPTR,struct KeyMap *);
struct InputEvent *InvertString(STRPTR,struct KeyMap *);
FUNCTION
This function returns a linked list of input events which would translate into the string using the supplied keymap (or the system default keymap if 'km' is NULL).
'str' must be null-terminated and may contain:
An example is:
'str' must be null-terminated and may contain:
-
ANSI character codes
-
backslash escaped characters: \n - CR \r - CR \t - TAB \0 - illegal, do not use! \\ - backslash
-
a text description of an input event as used by ParseIX(), enclosed in angle brackets.
abc<alt f1>\nhi there.
INPUTS
- str
-
Null-terminated string to convert to input events
- km
-
Keymap to use for the conversion, or NULL to use the default system keymap.
RESULT
- events
-
A chain of input events, or NULL if there was a problem. The most likely cause of failure is an illegal description enclosed in angled brackets. Running out of available memory is possible, too. See the BUGS section for more information.
This chain should eventually be freed using FreeIEvents().
- NOTE:
-
The chain is always built in reverse order with the first input event of the chain corresponding to the last character or input expression text of the input string.
WARNING
InvertString() has always built the event chain in reverse order. The first event in the chain stands for the last character or input expression text of the input string to be processed.
This order makes the event chin suitable for use with the CxTranslate() function as well as SetTranslate() which is called by CxTranslate(). If you want to use this event chain for anything else, such as for AddIEvents(), then you will either need to flip the string before passing it to InvertString(), or flip the resulting list of input events.
This order makes the event chin suitable for use with the CxTranslate() function as well as SetTranslate() which is called by CxTranslate(). If you want to use this event chain for anything else, such as for AddIEvents(), then you will either need to flip the string before passing it to InvertString(), or flip the resulting list of input events.
BUGS
The characters which cannot be converted into a corresponding input event may be skipped or may produce input events with InputEvent.ie_Class == IECLASS_NULL. If InvertString() returns a valid pointer (not NULL) it does not necessarily mean that the string could be processed correctly.
Even though it says above that the backslash-escaped character "\0" is "illegal", InvertString() will not reject this attempt and will instead try to produce an input event which may not be attainable.
InvertString() will attempt to modify the input string if there are text descriptions of input events enclosed in angle brackets. These changes will be reversed, leaving the string unchanged before InvertString() returns. If the input string is stored in read-only memory then the results will be unpredictable. If the same input string is shared by several Tasks or interrupt code you should take precautions for arbitration, such as the use of SignalSemaphores or the Disable() / Enable() functions.
To use backslash-escaped character sequences other than \n, \r, \t, \0 and \\ may cause InvertString() to abort and return NULL.
Even though it says above that the backslash-escaped character "\0" is "illegal", InvertString() will not reject this attempt and will instead try to produce an input event which may not be attainable.
InvertString() will attempt to modify the input string if there are text descriptions of input events enclosed in angle brackets. These changes will be reversed, leaving the string unchanged before InvertString() returns. If the input string is stored in read-only memory then the results will be unpredictable. If the same input string is shared by several Tasks or interrupt code you should take precautions for arbitration, such as the use of SignalSemaphores or the Disable() / Enable() functions.
To use backslash-escaped character sequences other than \n, \r, \t, \0 and \\ may cause InvertString() to abort and return NULL.