lyx_mirror/src/frontends/qt2/README

This file contains some do's and dont's for the Qt2 frontend.

General rules
-------------

Every editable field that affects the state of the dialog contents
from LyX's point of view should connect its xxxChanged() signal to
a the dialog's changed_adaptor() slot, which in turn should call
form_->changed(). If you are using a more complicated thing anyway,
then remember to call form_->changed() at the end (if it has changed !)
 
Every non-trivial widget should have a tooltip. If you don't know
what to write, write "FIXME", and it can fixed later. Don't be afraid
to use QWhatsThis too, but this must be done in the derived class's
constructor, and use _("..."). Non-trivial means that things like "OK"
/must not/ have a tooltip.
 
If necessary, you should override Qt2Base::isValid() for determining the validity
of the current dialog's contents.
 
OK/Apply/Restore/Close should be connected in the derived class's constructor
to call form_->slotOK() etc. Refer to close/cancel as close in the source.
 
Override update_contents() to update the dialog, not update(), and build_dialog(),
not build(). Only these functions may change dialog widgets that may emit changed()
during initialisation, to prevent the button controller from changing its state.

Never call buttoncontroller functions directly from dialogs. In general, you
should use Qt2Base::changed() in all circumstances. However, if you must call
the buttoncontroller, make sure to respect Qt2Base::updating_

Don't #undef emit - #include "QtLyXView.h" instead
 
Naming conventions
------------------

QFoo.[Ch]              The file that interacts with the controller
QFooDialog.[Ch]        The implementation of the dialog, derived from the generated files
ui/QFooDialog.ui       The designer file
ui/QFooDialogBase.[Ch] Generated files from QFooDialog.ui
 
slots should be named e.g. slotFooClicked(), slotFooSelected(), where foo is the name
of the widget.
 
Widgets should be named like "fooXX", where XX is one of the following
widget types :

CB - check box 
CO - combo box
ED - line edit
LA - label
ML -
PB - push button
(FIXME: complete this)

 
Dialog		Maintainer	MVC conversion
----------------------------------------------
About		John		Done
Bibitem		John		Done
Bibtex		John		Done
Character	Edwin		Done
Citation	Kalle		Done
Document	Kalle		Waiting for MVC
ERT		John		Done
Error		John		Done 
External	John		Done 
Graphics	John		Done
Include		John		Done 
Index		Kalle		Done
Log		John		Done
Minipage	John		Done 
Paragraph	Edwin		Waiting to be updated
Preamble	John		Done
Print		Edwin		Done
Ref		Kalle		Done
Search		Edwin		Done
Spellchecker	John		Done
Splash		Edwin
Tabular				Waiting for MVC
TabularCreate	Edwin		Done
Thesaurus	John		Done
Toc		Kalle		Waiting to be updated
Url		Kalle		Done
VCLog		John		Done


Stuff to be aware of
--------------------

The connect statement in Qt is a macro and its arguments does not follow
the C++ standard as it should. Using the construct "Type const &" as
argument will lead to runtime-errors, use "const Type &" instead.

ex.

--right--

	connect(list, SIGNAL(selected(const QString &)),
		this, SLOT(complete_selected(const QString &)));

--wrong--

	connect(list, SIGNAL(selected(QString const &)),
		this, SLOT(complete_selected(QString const &)));