User Tools

Site Tools


wiki:platformspecifics

Using StyleGuide class for control layout

The different platforms FlameRobin is supported on (MS Windows with wxMSW, GTK on different systems with wxGTK, Mac OS X with wxMAC) each have their own rules for UI design, layed out in more or less detail in the HIG (Human Interface Guidelines). While wxWidgets tries to follow those rules this does not work everywhere, and in some areas (most prominently the spacing of controls in frames and dialogs) the user of the library has to provide their own solution.

To make FlameRobin follow the HIGs as closely as possible a StyleGuide class has been created as a central facility to query information about control spacing. The class has one instance in FlameRobin, returned by the styleguide() function.

Using AdvancedMessageDialog as replacement for wxMessageBox()

The wxMessageBox() function in the wxWidgets API is not really suitable for presenting HIG-conforming alert dialogs. It has the parameters dialog caption and message text, while both the GNOME and the Mac OS X HIG call for both a (short) primary and a (longer and more verbose) secondary message. All three supported platforms don't use the alert caption for important text, the alert has either no caption at all, or should contain the application name only.

For these reasons a new class AdvancedMessageDialog has been created (still a work in progress), that tries to implement all of the HIG rules and suggestions. It should however not be used directly, several helper functions are provided to give easy access to the functionality:

  • showInformationDialog()
  • showQuestionDialog()
  • showWarningDialog()
  • showErrorDialog()

New code should no longer use the wxMessageDialog() function, but call one of these. The remaining occurences of wxMessageDialog() should be replaced in time.

There are two versions of the functions, one to only show the alert dialog:

  int res = showQuestionDialog(this, _("Do you really want to quit FlameRobin?"),
    _("All uncommitted transactions will be rolled back, and any uncommitted changes will be lost."),
    AdvancedMessageDialogButtonsOkCancel(_("&Quit")));

and the other one to additionally show a checkbox to suppress further appearance of the alert dialog:

  int res = showQuestionDialog(this, _("Do you really want to quit FlameRobin?"),
    _("All uncommitted transactions will be rolled back, and any uncommitted changes will be lost."),
    AdvancedMessageDialogButtonsOkCancel(_("&Quit")),
    config(), wxT("DIALOG_ConfirmQuit"), _("Always quit without asking"));

The primary text parameter should consist of one short but complete sentence, stating the cause of the alert or asking the question. The secondary text parameter should contain any explanatory text. Both should not contain any line breaks, as the text is wrapped automatically, and fixed line breaks may not look good in translated text. The separation of paragraphs in the secondary text is of course possible.

The text for the checkbox should be short, but describe what the checked box will cause to happen. This should be as clear as possible; text like “Always connect without asking” is preferable to “Do not ask again”.

wiki/platformspecifics.txt · Last modified: 2013/07/11 21:30 by mariuz