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 form_->changed(). If you are using a more complicated thing anyway,
  10 then remember to call form_->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 is incredibly stupid and sometimes you need a fully qualified
  19 "std::string" for .connect() statements to work. Be very, very careful.
  20
  21 Remember to check tab order on a dialog (third icon, with blue bars in designer).
  22
  23 Remember to check sensible resizing behaviour on a dialog.
  24
  25 Remember to use Edit->Check Accelerators
  26
  27 If necessary, you should override Qt2Base::isValid() for determining the validity
  28 of the current dialog's contents.
  29
  30 OK/Apply/Restore/Close should be connected in the derived class's constructor
  31 to call form_->slotOK() etc. Refer to close/cancel as close in the source.
  32
  33 Override update_contents() to update the dialog, not update(), and build_dialog(),
  34 not build(). Only these functions may change dialog widgets that may emit changed()
  35 during initialisation, to prevent the button controller from changing its state.
  36
  37 Never call buttoncontroller functions directly from dialogs. In general, you
  38 should use Qt2Base::changed() in all circumstances. However, if you must call
  39 the buttoncontroller, make sure to respect Qt2Base::updating_
  40
  41 Naming conventions
  42 ------------------
  43
  44 QFoo.[Ch]              The file that interacts with the controller
  45 QFooDialog.[Ch]        The implementation of the dialog, derived from the generated files
  46 ui/FooDialog.ui       The designer file
  47 ui/FooDialogBase.[Ch] Generated files from FooDialog.ui
  48
  49 slots should be named e.g. slotFooClicked(), slotFooSelected(), where foo is the name
  50 of the widget.
  51
  52 Widgets should be named like "fooXX", where XX is one of the following
  53 widget types :
  54
  55 CB - check box
  56 CO - combo box
  57 ED - line edit
  58 GB - group box
  59 LA - label
  60 LC - LengthCombo
  61 LV - QListView
  62 ML - QTextBrowser
  63 PB - push button
  64 RB - radio button
  65 SB - spin box
  66 SL - slider
  67 TE - text edit
  68 TW - tree widget (FIXME: also TV in some files)
  69
  70
  71 Stuff to be aware of
  72 --------------------
  73
  74 The connect statement in Qt is a macro and its arguments does not follow
  75 the C++ standard as it should. Using the construct "Type const &" as
  76 argument will lead to runtime-errors, use "const Type &" instead.
  77
  78 ex.
  79
  80 --right--
  81
  82         connect(list, SIGNAL(selected(const QString &)),
  83                 this, SLOT(complete_selected(const QString &)));
  84
  85 --wrong--
  86
  87         connect(list, SIGNAL(selected(QString const &)),
  88                 this, SLOT(complete_selected(QString const &)));
  89
  90 Qt, Unicode, and LyX
  91 --------------------
  92
  93 LyX uses a different encoding (UCS4) than Qt (UTF16), therefore there are a
  94 number of conversion functions in qt_helpers.[Ch]. Read the doxygen
  95 documentation for details when to use which function.
  96
  97 Additionally, you should follow these simple rules :
  98
  99 o Use qt_() not _() in code
 100 o Use the conversion functions of qt_helpers.h, NOT .latin1() / .c_str() etc.