text_command_helper [MMOMinion Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======= Text Command Helper (TCH) =======
{{:mistahmikey:textcommandhelper:text_command_helper.png?400|}}

===== What it does ===== 

TCH allows you to create aliases for long FFXIV text commands that you can subsequently indirectly execute from within FFXIV macros or via the chat window by referencing the aliases.  The FFXIV text command arguments associated with an alias can be up to 1022 characters in length - a substantial increase in what is typically allowed within the game for both the chat window and macro lines.  TCH allows you to pack more FFXIV text commands into your macros or more easily execute long chat FFXIV text command sequences from the chat window.

TCH provides this capability by leveraging the FFXIV 'echo' text command to submit aliases for execution. Using the TCH "exec" command (/e /exec), multiple aliases can be executed with a single exec command.  Additional features provided are:

   * The ability to specify fine-grained waits between alias executions, effectively providing a concise mini-macro capability
   * The ability to add color to arbitrary sections of an FFXIV text command
   * The ability to embed hexadecimal character strings that encode FFXIV UTF8 characters or FFXIV message tokens (for fancy characters like the die from the /random FFXIV text command)
   * The ability to paste FFXIV text commands into TCH from the clipboard that contain FFXIV UTF8 characters. 


The latter three features are useful for the various chat commands like /say, /shout, etc.

===== Requirements =====

You must also download MistahMikeysLib from the store. It's free, of course.

TCH supports the following languages:  EN, FR, JP, KR, and CN.

You must ensure FFXIV, Minion, and TCH are always updated to their latest versions.


======= Usage Description =======

You must use the FFXIV echo command to submit TCH's /exec command.  TCH will then execute the FFXIV text commands associated with their aliases.  You can initiate the /exec command via either including it on a macro line or typing it the the chat window, like so:

/e /exec <arg1>,<arg2>,...,<argn>

Each <arg> has the format <key>[=<value>]. White space is generally not significant.

The exec command arguments are defined in the following table.  All arguments are **case insensitive**.

| Key          | Value                 | Function                                                                                                                                                                                                                                                                                                                                                                                  |
| <alias>      | <no value>            | Used to specify an alias that you have previously associated with an FFXIV text command you want to execute.                                                                                                                                                                                                                                                                              |
| wait         | milliseconds to wait  | Used to specify the time you wish TCH to pause before executing the next argument.                                                                                                                                                                                                                                                                                          |

Any errors in exec command execution will result in a red message being displayed in the chat window.  For the FFXIV text commands you specify for an alias, TCH only checks for basic errors, such as a proper length and that it at least starts with something in the form of an FFXIV text command, i.e., /<text>. TCH does NOT check that <text> is a valid FFXIV text command, nor can TCH know if the FFXIV text command you executed was successful - you'll have to detect and debug such errors yourself.  TCH executes each argument serially, pausing whenever you specify a 'wait' argument before executing the next argument.  This effectively allows you to specify mini-macros using a single exec command.

Also supported is the ability to use color tags to color any part of the FFXIV text command you desire.  The color tags have the format:

<color text_to_be colored>

where 'color', which is case insensitive, can currently be white, black, red, orange, lime, blue, purple, yellow, aqua, fuchsia, gray, green, maroon, navy, olive, silver, teal, brown, pink, and gold. If you specify an unrecognized 'color', it defaults to white. The characters used to specify the color tag do not directly figure into the FFXIV text command arguments' length limitation.  However, before the final FFXIV text command can be executed, TCH encodes all the color tags using FFXIV color frames, and characters required to create the frame do figure into the command arguments length limitation.  This feature was provided primary for use with the FFXIV chat text commands, like /say, /shout, /party, etc.

You may also embed hexadecimal character strings that encode FFXIV UTF8 characters or FFXIV message tokens into your FFXIV command text. The embedded hexadecimal strings have the format:

[<hexadecimal digits>]

where

<hexadecimal digits> is the desired encoding, and must contain an EVEN number of hexadecimal digits.  For example, to embed the fancy die character that results from a /random FFXIV command, you would enter the FFXIV message token [0212024a03], or to embed the UTF8 die character, you would enter [ee80be].  A decent level of technical skill is required to figure out what the proper sequences are, but for those that have such skill, this allows you to create all manner of fancy messages. In the future I hope to add a tool to TCH that you can use to automatically format selected lines from the chat log to contain the proper embedded hexadecimal strings that correspond to the contained UTF8 characters and FFXIV message tokens. That will allow you to more easily create your own private catalog of encodings that you can cut/paste into commands as you please.

Since the < character is used to introduce color tags, and the [ character is used to introduce an embedded hexadecimal string, the ability to escape them (or any character) is provided by the \ character.  So to include < in and FFXIV text command, you'd type \<.

** Note: You must enable TCH in order for it to process the exec command. **


======= UI =======

You start TCH via the FFXIVMinion menu drop down. It's under the "MistahMikey" menu item.  Clicking "TextCommandHelper" should pop up its UI window.  The UI consists of different input areas called tabs that are selected by clicking the tab name that appears on the first line of the UI.  Each tab is described below.

__**GENERAL UI USAGE NOTE**__

When entering a value into a field control, when you begin to enter the text, the text will appear dimmed as a visual cue you are in the process of modifying the current value of the field.  The field value is not entered until you hit either the RETURN key or the TAB key, at which time the value might be checked, resulting in a popup if an error is detected. After dismissing an error popup, you should be returned to the field control to correct the error. If you navigate away from a field control by focusing other controls (say, by clicking in a different field control) before entering the value, the current value will be redisplayed and the value you were in the process of entering will be lost. You can use the ESC key to abort your current edit and replace it with the original value.

In the TCH control descriptions, if the control label has a asterisk appended, it means that value is saved in your profile (see the Profile Tab.)
===== Main Tab =====
{{:mistahmikey:textcommandhelper:main_tab.png?400|}}

This tab generally controls the overall operation of TCH. The top level controls on this tab are:

| Enabled* | When checked, enables you to travel to specified locations by issue a macro command.|
| Reset | Resets all settings to their default initial values. You can use this to abort certain operations you've started if you can catch it in time. If you have a current profile set, and Load Current Profile After Reset (Profile Tab) is enabled, then your saved profile values will be loaded.  The Reset button will disappear while the reset is in progress, and will reappear when it completes. |
| Discord Icon | Takes you to the TCH Discord channel if you need support.  Be advised I am in the Eastern Time zone (UTCH-05:00). |

Below those controls appears a table where you can persistently define aliases and their associated FFXIV text commands.  There are four columns in the table, but only the first three, Selection, Alias and Description, which should be self explanatory as to their purpose, are displayed; the fourth, FFXIV Text Command, cannot be completely displayed when the length becomes too long.  You can see the entire FFXIV text command by right double-clicking on the desired table line, resulting in a popup that shows all the text.

Above the table are two lines of controls. The first line is the Find control.  If your alias table becomes very long, you can use the Find control to specify an alias and it will be scrolled to the first line the table. The second line is a series of buttons:

| Add | Used to create a new alias. |
| Edit | Used to edit an existing alias. You must first check the appropriate alias you want to edit in the Selection column. |
| Delete | Used to delete existing aliases.  You must first check the appropriate aliases you want to delete in the Selection column. |

Both Add and Edit use the same basic control to allow you to enter or modify and Alias, Description, and FFXIV Text Command.

{{:mistahmikey:textcommandhelper:enter_alias_info_popup.png?400|}}

This control is self-explanatory for the most part; if you enter something wrong, TCH will provide an error popup. 

Because the product Minion provides developers to create a UI, IMGui, is a very old version, there isn't currently an easy way to enter the potentially long text strings you might want to associate with an alias via the Command text field.  I developed a kludge to at least provide for such entry, but the input text field can only be displayed on a single line in the UI. To somewhat mitigate this inconvenience, I also provide a view directly below that the Command text field that shows you a wrapped version of your complete command, and also displays the current lengths of both the FFXIV text command "verb" and it's arguments.  After some testing, I determined that the total length of all arguments can be no more than 1022 characters, and that includes any characters needed to encode color tags into FFXIV color frames, or any FFXIV special characters you encode or paste in.  The verb length does not appear to have any impact on the arguments length limitation.

Another quirk of the Command text field is that it is not possible to use Ctrl-V to paste certain FFXIV UTF8 characters into it because IMGui filters them out.  As another kludge workaround, I allow you to do this by using the Paste button that appears below the Command text field.  When you click the Paste button, the contents of the clipboard are appended to the current Command text field contents, and in this case, no characters from the clipboard are filtered out. This obviously isn't very user friendly, but it's the only way to get those special UTF8 characters into the Command text field.

I realize this method to enter a FFXIV text command is sub-optimal at best, but hopefully is better than nothing.  Be aware that as you edit the command, it will be dimmed to indicate you have changed it from the original, so be sure to hit the enter key before you try to exit the control.  


To enter what you have typed in the command control, you must hit the OK button at the bottom of the control.  I apologize for the clunkiness of the Command text field, but it is the best I could come up with at this time.  As a result, I suggest that you use an outside text editor to create the text you want, copy it to the clipboard, then use the Paste button to put it into the Command control.

Finally, if you have the requisite technical skill, you can use the hexadecimal string embedding feature to encode any fancy character you desire.

Here is the result of executing this particular alias.

{{:mistahmikey:textcommandhelper:command_execution_example.png?400|}}

As you can see, TCH uses the echo command to send the /exec command to the chat window. TCH sees this, and executes the command.  The result:  my multicolored carnival barker shout with embedded die characters touting the virtues of TCH; the name has been blanked out to protect the guilty.

Theoretically, you should be able to execute any FFXIV text command using TCH. However, as I am but one person, and rarely use FFXIV text commands myself, I have not tested this theory even remotely rigorously. As always, if anything odd pops up, just refer to the support section in this wiki and submit your issue.


===== Profile Tab =====
{{:mistahmikey:taximan:profile_tab.png?400|}}

The Profile Tab allows you to persistently store most of TCH's settings. The profile settings are stored in files unique to the character and game language used to create the profile. You can create as many profiles as you like. The controls on this tab are:

| Load Current Profile After Reset* | When checked, if you hit Reset on the Main Tab, or when TCH is loaded when you start Minion, after all settings are initialized to their default values, the saved settings in your current profile are loaded. |
| Current Profile Name* | The settings file you selected to be the current profile being used by TCH. |
| Load | Load all settings from the current profile. |
| Save | Save all settings to the current profile. |
| Add New Profile | The name of a new profile you wish to add (must be a valid file name). |
| Add | Create the new profile and save all current settings to it. |

The table is a list of all the profiles you have created for the current character and game language.  Using the "Selection" column, you can select specific profiles for the operations Delete or Make Current.  Obviously, only one profile at a time can be made current, so you can only select one for that operation, but you can select as many as you like for the Delete operation.  You can select/deselect all profiles by using the checkbox in the operation row.  ** Be aware that profile values are only saved when you explicitly request them to be saved via the Save button. **


===== Debug Tab =====

{{:mistahmikey:taximan:debug_tab.png?400|}}

This tab is primarily intended for use in conjunction with consultation with TCH support.  It enables various test scenarios and debugging information that are used to help diagnose issues that might occur during TCH's operation.  The controls on this tab are:

| Enable Log file* | When checked, TCH will create a unique log file for your session. This only needs to be checked if you are told to do so by TCH support. |
| Enable Timestamp* | When checked, TCH will include the current tick count in the debug messages. This provides information that facilitates debugging timing issues. |
| Debug Message Level Settings* | TCH's debug message system implements a simple filtering mechanism that can be used to allow or inhibit certain message classes, generally in increasing order of verbosity.  The default settings are fairly "quiet", but to debug issues you encounter you will be asked to enable more verbose settings to gather diagnostic information. |

====== Support ======

For bug support, please post a message on discord: https://discord.gg/Awhk57EBuG.  I will respond as soon as I am able, generally within 24 hours at most.

When you need support, please provide me, at a minimum, the following:

  - Enable the debug information category on the Debug Tab and do what you did to create the problem.  Then take a screen shot of your Minion Console Log when the problem occurs. Make sure the Log's window as big as possible to show the maximum amount of output.  If the output is larger than the window, then scroll the offscreen portions into view and send multiple screen shots.
  - A screen shot of your Material Girl main tab

If you post this information to the specified channel (NOT RECOMMENDED), **please ensure it does not contain any information that identifies your account, character, or server.**  For complete anonymity, just DM it to mistahmikey#4073.
Additionally, **you should not use an account you use for in-game communications so you can't be doxed as a botter. **

If that initial information is insufficient for me to determine the cause, I will ask you to set other debug settings that will provide more information. TCH is a complex piece of software, and can be negatively affected by a number of factors over which I have no control, not the least of which is what other addons you run. I appreciate your patience in working with me to solve your issue when it is not slam-dunk easy. As long as you are willing to try the debugging measures I request, I will work with you until your problem is solved.
User Tools

Site Tools

Page Tools
