development/Code_rules/Popups

   1 Rules for the use of popups
   2 ===========================
   3
   4 We need to have some rules in order to keep LyX enjoyable to use.  This
   5 document describes the rules for designing popups.  Please obey the rules.
   6 If you don't do it correctly, somebody else has to fix it for you, and we
   7 don't like to waste time because you were lazy.  So, read it now, design
   8 your popups, and come back and check if your new popup is in compliance.
   9
  10 Internationalization
  11 --------------------
  12
  13 We need some rules to be followed so that popups and short-cuts will
  14 work properly with regard to internationalization and gettext.
  15
  16 We have made a method to make the shortcuts in xforms work correctly with
  17 internationalizationed shortcuts. We concat the label and the shortcut like
  18 this:
  19
  20         <ident>|<shortcut>  (where <ident> often is a label)
  21
  22 And have made two funcs to extract that info: scex and idex
  23 (shortcut-extract and ident-extract). To minimize the translation effort
  24 you should use stuff like:
  25
  26         fl_add_object(<params>, idex(_("<ident>|<shortcut>")));
  27         fl_set_shortcut(<obj>, scex(_("<ident>|<shortcut>")));
  28
  29 Make sure the two texts are identical, such that gettext will join them.
  30
  31 This will also help use make the labels and shortcuts consistent across
  32 all the dialogs.
  33
  34 Some <ident>|<shortcuts> pairs have been decided:
  35
  36 1. Most popups have at least three buttons in common:
  37
  38         - OK            No shortcut in the usual case (it is a return button)
  39         - Apply         "Apply|#A"
  40         - Cancel        "Cancel|^[" (This is the escape key)
  41                         You can optionally use "Cancel|#C^[" also.
  42         - Close         Either return-button, "Close|^[" or "Close|#C^[".
  43
  44 Design rules
  45 ------------
  46
  47 1) Remember that you have to add this function to your form definition:
  48
  49                 fl_set_form_atclose(form, CancelCloseBoxCB, NULL);
  50
  51    to prevent crashes when the users close the popup with the window manager.
  52    You need to #include "lyx_gui_misc.h" to get CancelCloseBoxCB.
  53
  54 More will follow...
  55
  56 NB! If any of the shortcut keys is a part of the label and you want it to
  57 be underlined in the label, that character must be the _first_ in the
  58 accelerator string (allthough it may be an alt-key etc). Case _sensitive_.
  59   Apply|Pp#p#P     won't get an underlined 'p'
  60   Apply|GpaAP      won't either.
  61   Apply|aA         nope
  62   Apply|pP#p#P     will underline the first 'p'
  63   Apply|Aa         will underline the 'A'
  64   Apply|#Aa        will also underline the 'A'!
  65 See the docs for xforms... (fl_set_shortcut() etc)
  66 It seems xforms .86 doesn't recognise 128+ chars as shortcuts. (not with
  67 fl_set_shortcut() anyway)  /Joacim