Latest Posts

Topic: Styling and richtext.lua

tothxa
Avatar
Topic Opener
Joined: 2021-03-24, 12:44
Posts: 436
OS: antix / Debian
Version: some new PR I'm testing
Ranking
Tribe Member
Posted at: 2023-01-08, 01:28

Working on #5717 I came to realise that keyboard shortcut help would be much better autogenerated. This led me to examine how formatting works, and I was surprised that:

  • higher level / structured formatting is only implemented in richtext.lua
  • and that there the appearance of each element is hard-coded

I gather making all UI styleable is one of our important development goals, so I wonder how these problems should be solved.

  • Should the richtext language be extended with the higher level tags? But that would need style handling in rt_render.cc too. Or expand them in rt_parse.cc? Maybe that would make more sense…
  • Or just add as_<tag> functions in text_layout.{h,cc}? But then either it would be separate from richtext.lua, or each of these functions should be exposed to lua. I don't think this would be nice. OTOH adding those functions for inserting the higher level tags if added to the richtext syntax as above would probably be helpful. It would then be the C++ equivalent of richtext.lua.

Then what should be the name of the style that is now implemented in richtext.lua? Maybe just markup? I think it has several uses, most notably the Encyclopedia / Editor Help, campaign dialogs, objectives and in game messages to the player. Do we want to support using more than one style for markup for any of these (or possible other) different use cases? (not meaning switching to user defined / selectable styles, which is a separate issue)


Top Quote
Nordfriese
Avatar
Joined: 2017-01-17, 18:07
Posts: 1929
OS: Debian Testing
Version: Latest master
Ranking
One Elder of Players
Location: 0x55555d3a34c0
Posted at: 2023-01-08, 10:38

I'm not sure what you mean exactly. Both richtext.lua and text_layout.* simply provide wrappers around richtext tags.

For maximum control, you can write text with tags directly, like

<p align=center><font italic=1 color=123456>Hello World</font></p>

Or you can use the convenience functions, like

Lua:
p("align=center", font("italic=1 color=123456", "Hello World"))
C++:
as_richtext_paragraph("Hello World", UI::FontStyle::..., UI::Align::kCenter)

The Lua wrappers have the problem that colours and fontsizes are hardcoded, but this will eventually be fixed in the wrapper, to fix all use cases at once. This is also why you shouldn't use direct styling for anything that a theme should be able to modify – the C++ way uses theme-specific colours and font sizes, with direct styling that responsibility falls to you. Except for simple, non-theme-specific tags like <div> which you can use liberally.


Top Quote
tothxa
Avatar
Topic Opener
Joined: 2021-03-24, 12:44
Posts: 436
OS: antix / Debian
Version: some new PR I'm testing
Ranking
Tribe Member
Posted at: 2023-01-08, 13:12

I mean functions in richtext.lua like e.g.:

function h2(text)
   return p_font("", "size=14 bold=1 color=D1D1D1", vspace(12) .. text .. vspace(1))
end
  • This has no equivalent in the C++ code (I expected something like an as_h2(std::string text) in text_layout.{h,cc})
  • I thought there was a <h2> tag in the richtext language, so h2() would just add that
  • I din't expect that formatting like font size, font style, colour and spacing would be hardcoded in richtext.lua
  • I'm not sure if it's possible to get the current template_dir in lua

So I'd like to correct these things, and my questions are about what the right approach would be.


Top Quote
Nordfriese
Avatar
Joined: 2017-01-17, 18:07
Posts: 1929
OS: Debian Testing
Version: Latest master
Ranking
One Elder of Players
Location: 0x55555d3a34c0
Posted at: 2023-01-08, 13:36

This is all part of the bigger task of placing all UI elements under the theme's control. Lua code should not hardcode any font size or colour attributes; instead those should be fetched from C++ which looks them up in the current theme's definition.

So the proper way would be to add a function to the Lua interface as_font_style(name, text) which acts as a wrapper around g_style_manager->font_style(UI::FontStyle::<name>).as_font_tag(text). For headings and the like, we should use the UI::FontStyle::k***Heading styles, and possibly add a few more of these for subheadings.

In C++ then simply use g_style_manager->font_style(UI::FontStyle::k***Heading).as_font_tag(text) or some such as usual (though it would not hurt to add a one-line wrapper as_font_tag(UI::FontStyle, const std::string&) for this very common call to text_layout.h).

I'm not sure if it's possible to get the current template_dir in lua

You shouldn't need to, especially after https://github.com/widelands/widelands/pull/5734


Top Quote
tothxa
Avatar
Topic Opener
Joined: 2021-03-24, 12:44
Posts: 436
OS: antix / Debian
Version: some new PR I'm testing
Ranking
Tribe Member
Posted at: 2023-01-08, 14:31

OK, I think I can do this for everything that currently has hardcoded style in richtext.lua. But headings also have vspace, so I guess there will have to be an as_paragraph_style(style_name, text) function and a ParagraphStyleInfo struct too.

Now to the last part of the original post: What common prefix should I use for the font and paragraph styles extracted from richtext.lua?


Top Quote
Nordfriese
Avatar
Joined: 2017-01-17, 18:07
Posts: 1929
OS: Debian Testing
Version: Latest master
Ranking
One Elder of Players
Location: 0x55555d3a34c0
Posted at: 2023-01-08, 15:00

tothxa wrote:

OK, I think I can do this for everything that currently has hardcoded style in richtext.lua. But headings also have vspace, so I guess there will have to be an as_paragraph_style(style_name, text) function and a ParagraphStyleInfo struct too.

+1

Now to the last part of the original post: What common prefix should I use for the font and paragraph styles extracted from richtext.lua?

Most other functions in text_layout are called as_heading, as_listitem, as_richtext_paragraph etc, so unabbreviated names with the as_ prefix, e.g. as_heading, as_subheading, as_subsubheading etc, would be the most consistent IMHO.


Top Quote
tothxa
Avatar
Topic Opener
Joined: 2021-03-24, 12:44
Posts: 436
OS: antix / Debian
Version: some new PR I'm testing
Ranking
Tribe Member
Posted at: 2023-01-08, 15:18

Nordfriese wrote:

Now to the last part of the original post: What common prefix should I use for the font and paragraph styles extracted from richtext.lua?

Most other functions in text_layout are called as_heading, as_listitem, as_richtext_paragraph etc, so unabbreviated names with the as_ prefix, e.g. as_heading, as_subheading, as_subsubheading etc, would be the most consistent IMHO.

Sorry, I meant font and paragraph styles in templates/default/init.lua and the constant names in enum class FontStyle.


Top Quote