src/frontends/qt2/README

   1 This file contains some do's and dont's for the Qt2 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 If necessary, you should override Qt2Base::isValid() for determining the validity
  19 of the current dialog's contents.
  20
  21 OK/Apply/Restore/Close should be connected in the derived class's constructor
  22 to call form_->slotOK() etc. Refer to close/cancel as close in the source.
  23
  24 Override update_contents() to update the dialog, not update(), and build_dialog(),
  25 not build(). Only these functions may change dialog widgets that may emit changed()
  26 during initialisation, to prevent the button controller from changing its state.
  27
  28 Never call buttoncontroller functions directly from dialogs. In general, you
  29 should use Qt2Base::changed() in all circumstances. However, if you must call
  30 the buttoncontroller, make sure to respect Qt2Base::updating_
  31
  32 Don't #undef emit - #include "QtLyXView.h" instead
  33
  34 Naming conventions
  35 ------------------
  36
  37 QFoo.[Ch]              The file that interacts with the controller
  38 QFooDialog.[Ch]        The implementation of the dialog, derived from the generated files
  39 ui/QFooDialog.ui       The designer file
  40 ui/QFooDialogBase.[Ch] Generated files from QFooDialog.ui
  41
  42 slots should be named e.g. slotFooClicked(), slotFooSelected(), where foo is the name
  43 of the widget.
  44
  45 Widgets should be named like "fooXX", where XX is one of the following
  46 widget types :
  47
  48 CB - check box
  49 CO - combo box
  50 ED - line edit
  51 LA - label
  52 ML -
  53 PB - push button
  54 (FIXME: complete this)
  55
  56
  57 Dialog          Maintainer      MVC conversion
  58 ----------------------------------------------
  59 About           John            Done
  60 Bibitem         John            Done
  61 Bibtex          John            Done
  62 Character       Edwin           Done
  63 Citation        Kalle           Done
  64 Document        Kalle           Waiting for MVC
  65 ERT             John            Done
  66 Error           John            Done
  67 External        John            Done
  68 Graphics        John            Done
  69 Include         John            Done
  70 Index           Kalle           Done
  71 Log             John            Done
  72 Minipage        John            Done
  73 Paragraph       Edwin           Waiting to be updated
  74 Preamble        John            Done
  75 Print           Edwin           Done
  76 Ref             Kalle           Done
  77 Search          Edwin           Done
  78 Spellchecker    John            Done
  79 Splash          Edwin
  80 Tabular                         Waiting for MVC
  81 TabularCreate   Edwin           Done
  82 Thesaurus       John            Done
  83 Toc             Kalle           Waiting to be updated
  84 Url             Kalle           Done
  85 VCLog           John            Done
  86
  87
  88 Stuff to be aware of
  89 --------------------
  90
  91 The connect statement in Qt is a macro and its arguments does not follow
  92 the C++ standard as it should. Using the construct "Type const &" as
  93 argument will lead to runtime-errors, use "const Type &" instead.
  94
  95 ex.
  96
  97 --right--
  98
  99         connect(list, SIGNAL(selected(const QString &)),
 100                 this, SLOT(complete_selected(const QString &)));
 101
 102 --wrong--
 103
 104         connect(list, SIGNAL(selected(QString const &)),
 105                 this, SLOT(complete_selected(QString const &)));