src/frontends/qt4/README

   1 This file contains some do's and dont's for the Qt4 frontend.
   2
   3 General rules
   4 -------------
   5
   6 Every editable field that affects the state of the dialog contents
   7 from LyX's point of view should connect its xxxChanged() signal to
   8 a the dialog's changed_adaptor() slot, which in turn should call
   9 changed(). If you are using a more complicated thing anyway,
  10 then remember to call changed() at the end (if it has changed!)
  11
  12 Every non-trivial widget should have a tooltip. If you don't know
  13 what to write, write "FIXME", and it can fixed later. Don't be afraid
  14 to use QWhatsThis too, but this must be done in the derived class's
  15 constructor, and use _("..."). Non-trivial means that things like "OK"
  16 /must not/ have a tooltip.
  17
  18 moc needs a fully qualified "std::string" for .connect() statements
  19 to work. Be very, very careful.
  20
  21 Remember to check tab order on a dialog (third icon, with blue bars in
  22 designer).
  23
  24 Remember to check sensible resizing behaviour on a dialog. This is
  25 usually done by adding a top-level layout to the dialog in Designer.
  26
  27 Remember to use Edit->Check Accelerators
  28
  29 If necessary, you should override Qt2Base::isValid() for determining the
  30 validity of the current dialog's contents.
  31
  32 OK/Apply/Restore/Close should be connected in the derived class's
  33 constructor to call slotOK() etc. Refer to close/cancel as close in the
  34 source.
  35
  36 Override update_contents() to update the dialog, not update().  Only
  37 these functions may change dialog widgets that may emit changed() during
  38 initialisation, to prevent the button controller from changing its
  39 state.
  40
  41 Never call buttoncontroller functions directly from dialogs. In general,
  42 you should use Qt2Base::changed() in all circumstances. However, if you
  43 must call the buttoncontroller, make sure to respect Qt2Base::updating_
  44
  45 Naming conventions
  46 ------------------
  47
  48 QFoo.{cpp,h}     The file that interacts with the controller _and_
  49 the implementation of the dialog, derived from the generated files
  50 ui/FooDialog.ui  The designer file
  51 ui_FooDialog.h   Generated files from FooDialog.ui
  52
  53 slots should be named e.g. slotFooClicked(), slotFooSelected(), where
  54 foo is the name of the widget.
  55
  56 Widgets should be named like "fooXX", where XX is one of the following
  57 widget types :
  58
  59 CB - check box
  60 CO - combo box
  61 ED - line edit
  62 GB - group box
  63 LA - label
  64 LC - LengthCombo
  65 LV - QListView
  66 ML - QTextBrowser
  67 PB - push button
  68 RB - radio button
  69 SB - spin box
  70 SL - slider
  71 TE - text edit
  72 TW - tree widget (FIXME: also TV in some files)
  73
  74
  75 Qt, Unicode, and LyX
  76 --------------------
  77
  78 LyX uses a different encoding (UCS4) than Qt (UTF16), therefore there are a
  79 number of conversion functions in qt_helpers.{cpp,h}. Read the doxygen
  80 documentation for details when to use which function.
  81
  82 Additionally, you should follow these simple rules :
  83
  84 o Use qt_() not _() in code
  85 o Use the conversion functions of qt_helpers.h, NOT .latin1() / .c_str() etc.