Open main menu

RTL GUI Overview

What is this about?
The latest developmental build of ScummVM now supports an RTL based GUI. The main purpose of this is to adapt to RTL languages such as Hebrew, Arabic, etc.
RTL means Right-To-Left. RTL users read their content beginning from the right and then moving towards the left.


In ScummVM
If you want to preview how it looks (keep in mind that these will work on the latest developmental branch), you can add a "guiRTL = true" key in the scummvm.ini configuration file to force RTL. Or, you can switch a native RTL language. (Currently, it is only enabled for Hebrew)


How does it work?
The main constructs to enable RTL, within the code are:

  1. Main GUI-RTL, which you can check via g_gui.useRTL(). This is currently only enabled for Hebrew, but more languages can be added in GuiManager::setLanguageRTL() (located in gui/gui-manager.cpp)
  2. RTL for an individual widget, which is checked via _useRTL (for each GUI object).
    _useRTL is true by default. This shouldn't be a concern, because it always checks g_gui.useRTL() whenever working in an RTL based GUI.
  3. Overlaying Offset - this is used in the context of a stacked dialog. More information below.


I am adding some things to GUI, I would also like them to support RTL.
The following section has some notes that are needed to be kept in mind when designing new items or additions to the GUI - to adapt to RTL also.


RTL based GUI in code:

General notes

- The mouse coordinates are not calculated differently for RTL based GUI. They are just flipped from the normal GUI, so this shouldn't be a problem when creating new things within the GUI.
- Everything in the normal GUI will basically be flipped around, by calculating the reverse coordinates on the go.

Stacked Dialogs

If you are creating a stacked dialog, you will need to do the following things to adapt it for the RTL counterpart:

  1. Navigate to ThemeLayout.cpp, in ThemeLayoutMain::reflowLayout()
  2. Within there, you'll see a check like if (g_gui.useRTL) then if (_name......)
  3. Simply add the name of the stacked dialog here like:

this->_name == "stacked-dialog-name"

This sets the left+right coordinates of the stacked dialog. (Picture below)

  1. Navigate to Widget.cpp, in Widget::draw().
  2. Within there, you'll see a check like if (g_gui.useRTL()) then if (_name.....)
  3. Simply add the name of the stacked dialog here like:

this->_name.contains("stacked-dialog-name")


Why do I need to add these things for stacked dialogs?
The reason why we make this modification in Widget::draw(), is to shift the widgets when a stacked dialog is opened. This shift is added by calling g_gui.getOverlayOffset(), which is set when the name of the stacked dialog is added in ThemeLayout.cpp. This is set to 0 when the stacked dialog is closed.


RTL Widgets:

Some widgets are supposed to look differently for RTL. Here is an example:

If you're adding in support for a new widget, and also want to add in support for it's RTL counterpart - but wish to keep it disabled by default: Navigate to the ..._layout.stx and set rtl = 'no'

This will disable _useRTL, effectively disabling it by default. One such example currently is SliderWidgets.