3.22 MUI Royale compatibility

RapaGUI started as a fork of the popular MUI Royale plugin for Hollywood and people familiar with MUI Royale will no doubt see that RapaGUI shares the very same design so porting applications from MUI Royale to RapaGUI isn't particularly difficult. Although there have been many semantic changes to abstract RapaGUI from AmigaOS-based terminology, the real design differences are actually very few. Thus, when porting applications from MUI Royale to RapaGUI most of the time you will just be busy with changing names. Most people probably won't even encounter one of the very few design differences between MUI Royale and RapaGUI. Still, here is a non-exhaustive list of design differences between MUI Royale and RapaGUI to simplify your porting endeavours:

• – MUI Royale required you to handle Window.CloseRequest for all your windows or they would stay open. RapaGUI automatically closes windows that haven't got a listener for Window.CloseRequest installed.

• – MUI Royale also required you to handle the "HideWindow" and "ShowWindow" events to allow the minimizing of windows. RapaGUI handles this automatically now.

• – RapaGUI automatically sets up event handlers for buttons, toolbar buttons and menu items. MUI Royale required you to explicitly request them but this led to unnecessarily wordy XML files where you had to include something like notify="pressed" for each and every button because under normal circumstances you want to be notified about each button click. RapaGUI automatically calls your event handler for all button and toolbar button clicks and menu item events now to make the XML more readable.

• – RapaGUI automatically hides all Hollywood displays on startup whereas MUI Royale doesn't do this. On MUI Royale you manually have to declare the default display as hidden.

• – MUI Royale allows you to use text formatting codes almost everywhere. Since this is a highly MUI-centric feature, this is impossible to implement in a platform independent way. RapaGUI supports text formatting only in its Textview and Texteditor classes and only if Textview.Styled and Texteditor.Styled have been set to True.

• – MUI Royale also allowed you to include icons in almost all widgets via text formatting codes. This is also impossible to implement in a cross-platform way. Still, RapaGUI has icon support in many classes but the way this is implemented is always class dependent. On RapaGUI you can use icons with the following classes: Button class, Listview class, Pageview class, and Treeview class. Check out the documentation of these classes to learn more about how to use icons with them.

• – MUI Royale requires you to use an object derived from <virtgroup> class as the child for <scrollgroup> objects. On RapaGUI you can just use normal groups.

• – MUI Royale sends context menu events using the Area.ContextMenuTrigger attribute. RapaGUI simply sends context menu events as normal menu item events but it includes a Parent field in the event message to inform you about the widget whose context menu triggered the event.

• – RapaGUI's Checkbox class class creates a checkbox and a text label. MUI Royale's checkmark class simply creates a checkbox image and you have to create the label yourself.

• – RapaGUI doesn't have support for the Listview.InsertPosition attribute but its Listview.Insert method simply returns the position of the newly inserted entry.

• – In MUI Royale text editor ranges were indicated by block coordinates consisting of four different values (x1, y1, x2, y2). RapaGUI just uses start and stop coordinates now, so all the methods and attributes that deal with text ranges just require/return two arguments now.

• – RapaGUI's Texteditor class, Textview class, and Textentry class use the content between the opening and closing XML tags as the initial widget contents whereas MUI Royale always required you to use an attribute to set the initial contents.

• – RapaGUI requires you to specify a parent object most of the times when creating objects dynamically using moai.CreateObject(). This wasn't necessary in MUI Royale.

• – Since RapaGUI's Treeview class supports multiple columns, you have to create at least one <column> when declaring your treeview in XML. This wasn't needed with MUI Royale because its treeview class merely supports single column trees.

• – MUI Royale doesn't have the concept of dialogs since AmigaOS doesn't have it either. Modal dialogs were just emulated using normal windows and putting all other windows to sleep. RapaGUI now introduces real dialogs. While with MUI Royale you would typically create all those pseudo-dialogs at startup, this is no longer recommended with RapaGUI. Since windows are quite a finite resource on some operating systems, you should create dialogs only when you need them and destroy them immediately afterwards. See Dialog class for details. If you only target AmigaOS, then you can of course still create all your windows with just a single call to moai.CreateApp() but if you want to target other operating systems as well, you should follow the recommended programming guidelines and create dialogs when you need them and destroy them as soon as you are finished with them.

• – Objects of Radio class are always framed in RapaGUI. In MUI Royale they aren't framed by default.

• – When using a somewhat more complex shortcut string like CTRL+V, Alt+X or F5 with Menuitem.CommandString, MUI Royale doesn't automatically listen to it. This has to be implemented manually. Only standard shortcuts in the form of a single alphabetical key combined with the CMD key are handled automatically by MUI Royale. RapaGUI, however, automatically handles complex shortcuts as well.

• – When getting Listview.Active and no entry is active, MUI Royale returns the special string Off whereas RapaGUI returns -1.

Of course, there are also many attributes and methods that are present in MUI Royale but missing in RapaGUI. The reason for this is of course that because of its cross-platform design RapaGUI represents the lowest common denominator between Windows, Linux, macOS, and AmigaOS. That's why not all MUI Royale features could be transferred to RapaGUI.