How to start a new line in plugin help with localization?

Dunhou

Hey community,

I want to add plugin help (or tooltips), I can use embed string for \n, it works fine. but when I use c4d resource files (c4d_strings.str), it not worked, how can I fix this?

I can not paste imgs, (Something went wrong while parsing server response)
See Move Tool in c4d, it has 3 lines.

Cheers~
DunHou

ferdinand

Hey @Dunhou,

our c4d_string.str files use standard ASCII escaping (of unicode). There is the relatively new py-cmd_gui_resources_2024 example which documents this (of particular interest would be unicode_encode_strings.py for you). But when I wrote unicode_encode_strings.py, I think it was a deliberate decision of mine to exclude the so called control characters in ASCII/Unicode (i.e., \x00 to \x1F as Python Unicode escape sequences). Which includes the whitespace characters like \t, \n, \r, etc. So, the script will not encode them for you.

If you take the code example from above and wanted to add a line break in its help string, you cannot use \n in the string, because it would be escaped as \\n in the output, which is not what you want. Instead, you would have to use \x0A (i.e., the value 10 which is the code point for a line break in ASCII). But since this is not Python, but our C++ code which follows the Unicode standard to the letter, we do not use the \x prefix but \u and also pad it to 4 digits, so it would actually be \u000A for a line break.

STRINGTABLE
{
	IDS_PLUGIN_NAME "Py - Resource Gui"; 
	IDS_PLUGIN_HELP "Opens a dialog window that is populated\u000a using resource files.";
}

If you wanted a more generic solution than writing such strings by hand, you would have to update EscapeUnicode in unicode_encode_strings.py to something like this:

def EscapeUnicode(item: str) -> str:
    """Escapes both non-ASCII and control characters in a string to their unicode code point representation,
       e.g., \u000A for a line break.
    """
    return re.sub(r"([^\x00-\x7f]|\x00-\x1F)",
                    lambda m: "\\u{:04x}".format(ord(m.group(1))), item
    )

You could also just escape everything, but that would make the strings less readable in the resource files. I am personally also not sure it is a good idea to allow users putting control characters into strings, primarily due to whitespace. I would for example say that it is not wanted that strings in general and tooltips in particular contain line breaks, and that it is up to Cinema 4D to handle wrapping strings. When I look at our Move tool, I see no line breaks in the help string? The help string is just 'Move Tool', the other things (the name and the shortcut) are added by Cinema 4D dynamically (and therefore put onto a new line).

Cheers,
Ferdinand

Dunhou

Thanks for your tips!

@ferdinand said in How to start a new line in plugin help with localization?:

I am personally also not sure it is a good idea to allow users putting control characters into strings, primarily due to whitespace

I want to add some shortcut description to plugin like:

Plugin Name
description about.....
Alt : do something...
Shift : do something...

do you have suggestions about this case?

Cheers~
DunHou

ferdinand

It depends a bit on what you are doing. When you look at these screenshot I already posted above

then you can see, Cinema 4D is already doing this automatically. The tooltip for a command¹ is always split into a name, description and shortcut. As a plugin author, you define the name and description and Cinema 4D then composes them for the tooltip. The shortcut will only be shown when this command has a shortcut set, either because your user set it up, or because you programmatically set it in some sort of 'installer' routine for your plugin. That the Py - Resource Gui example does not have a shortcut shown, is simply due to the fact that I did not define one.

But your question implies a different type of 'shortcut', namely modifier keys. I.e., you do not want to display a key combination with which something can be activated (commands already fully handle this for you), but rather keys that change the behaviour of something while it is running. The canonical place to display such information would be the status bar. The Move tool shows for example this in the status bar once it has been activated (and a few other criteria are met):

Other than the command tooltips, this is not automated. And each plugin has to set this on its own via c4d.gui.StatusSetText. The problem is a bit that these kind of status messages make mostly sense for tools, i.e., things where you have clearly defined states of a thing being active or not, and when the user does send mouse- or keyboard interactions. These states help managing the status bar because you not only have to set these messages, you also have to clear the status bar once you are done.

So, it depends on what kind of plugin you implement how to do this concretely. When you implement just a command with a dialog, there is no predefined way how to do this, as dialogs are not meant to have such modifier keys. You could maybe show or hide such message based on if your dialog got or lost focus.

Cheers,
Ferdinand

¹ - Everything in this context is a command, even non CommandData plugins such as objects or tools, because Cinema 4D will always wrap them with a CommandData plugin for you, so that they can show up in palettes and menus. So, in menus and palettes are only commands, even when you did not implement one yourself.