kmymoney/developer-doc/phb/dialogs.docbook

  <chapter id="dialogs">
    <title>Creating dialog boxes in &kappname;</title>
    <para/>
    <para>This section is a developer's guide explaining the peculiarities of dialog creation in &kappname;. A basic understanding of Qt GUI programming is assumed, as is a knowledge of &kappname; coding standards as laid out in the Project Handbook.</para>
    <para/>
    <sect1 id="dialogs-language">
      <title>Language</title>
      <para/>
      <para>The default language of &kappname; is American English, but don't let that put you off! All contributions will be welcome, and as long as you have a basic knowledge of the language, the members of the &kappname; developers list will be happy to help you polish it up.</para>
      <para/>
    </sect1>
    <sect1 id="dialogs-naming">
      <title>Naming the dialog</title>
      <para/>
      <para>First step is to choose a meaningful name for your dialog (and preferably one that's not already in use! - see the kmymoney2/dialogs source directory). In accordance with &kappname; coding conventions, the name should consist of 2 or 3 (or more) 'words', strung together without spaces. To keep names to a manageable length, these 'words' may be abbreviated, e.g. 'sched' for 'schedule'. Each 'word' should be spelt with an initial upper-case letter. Also, the names of dialogs are always preceded by a letter 'K', thus e.g. KEditSchedTrans. This name will be indicated in the rest of this chapter by &lt;KN&gt;. There are nevertheless occasions where all lower case letters are appropriate, specifically source file names; this will be indicated as &lt;kn&gt;.</para>
      <para/>
    </sect1>
    <sect1 id="dialogs-designing">
      <title>Designing the dialog</title>
      <para/>
      <para>The dialog screen should be built using Qt Designer. This section assumes that you are using version 3.x of Qt. Version 4 is, at present, an unknown quantity.</para>
      <para/>
      <para>Open Designer without specifying a project, and select Dialog from the New File/Project tab. Start by changing the form name; this should be set to '&lt;KN&gt;DlgDecl'.</para>
      <para/>
      <para>Now add your widgets to the form, not forgetting to include a Help button. Remember that users will have many different hardware and screen combinations, and will need to be able to resize windows, so make full use of the various layout and spacer options of Designer. A lot of tutorials can be found on the web to help guide you on this; try your favourite search engine.</para>
      <para/>
      <sect2 id="dialogs-naming-widgets">
        <title>Naming widgets</title>
        <para/>
        <para>Fixed widgets, e.g. text labels, can often use the default names assigned by Designer. Other widgets on your form should be given names which are meaningful in an application context. This is particularly important for those widgets which are to be referenced in code. As per the application programming standards, these names should be prefixed with 'm_' to indicate them as member variables of the dialog.</para>
        <para/>
      </sect2>
      <sect2 id="dialogs-i18n-considerations">
        <title>i18n considerations</title>
        <para/>
        <para>Designer contains an option to generate shortcut (accelerator) keys for various widgets (buttons, menu items) by including an ampersand ('&amp;') before the shortcut letter. This should be used for the more common items, since many users prefer to use keyboard input rather than using the mouse. However, this does have the unfortunate side effect of automatically generating an 'accel' property for the widget, referencing a letter which may not be appropriate when the caption is translated to another language. Use the properties menu, therefore, to remove this value, or see below.</para>
        <para/>
        <para>Fixed text fields and labels in the form do not require any special consideration. Qt Designer and the project's build environment will take care of wrapping the strings into an i18n construct for presentation to translators.</para>
        <para/>
      </sect2>
      <sect2 id="dialogs-saving-ui">
        <title>Saving the UI</title>
        <para/>
        <para>When complete, save the form using the Designer default name (&lt;kn&gt;dlgdecl.ui) in the dialogs source code folder (kmymoney2/dialogs).</para>
        <para/>
      </sect2>
    </sect1>
    <sect1 id="dialogs-writing-code">
      <title>Writing code</title>
      <para/>
      <para>Your code to process form actions should be included in source files named &lt;kn&gt;dlg.h/.cpp, in the same folder as the .ui file. You can view these for many examples of how to code. Some requirements are:</para>
      <para/>
      <sect2 id="dialogs-header-file">
        <title>Header (.h) file</title>
        <para/>
        <para>This should start with definitions similar to the following</para>
        <para/>
        <programlisting>
   #ifndef &lt;KN&gt;DLG_H
   #define &lt;KN&gt;DLG_H</programlisting>
        <para/>
        <programlisting>
   #include "../dialogs/&lt;kn&gt;dlgdecl.h"</programlisting>
        <para/>
        <programlisting>
   class &lt;KN&gt;Dlg : public &lt;KN&gt;DlgDecl  {
   TQ_OBJECT
   public:
     &lt;KN&gt;Dlg(QWidget *parent = 0, const char *name = 0);
     ~&lt;KN&gt;Dlg();
        </programlisting>
        <para/>
        <para>The first two lines are the standard include stoppers, to avoid multiple inclusion of the class data.</para>
        <para/>
        <para>The include file will have been generated by the Qt UIC (User Interface Compiler) from the .ui file for the dialog, under control of the make process.</para>
        <para/>
        <para>The TQ_OBJECT macro (written without any punctuation) will cause the Qt MOC (Meta Object Compiler) to generate additional object code and files which are necessary to support the signal/slot functionality (among other things).</para>
        <para/>
        <para>The class declaration must also include a </para>
        <para/>
        <programlisting>   public slots:</programlisting>
        <para/>
        <para>and</para>
        <para/>
        <programlisting>   signals:</programlisting>
        <para/>

        <para>sections if you plan to use the signal/slot mechanism. See the Qt documentation about signals and slots. An example would be slotHelp() which will be connected to the clicked() signal of the help button of your dialog in the constructor of your dialog.</para>
        <para/>
        <para>Terminate the file with</para>
        <para/>
        <programlisting>   #endif</programlisting>
        <para/>
        <para>to close off the include stoppers.</para>
        <para/>
      </sect2>
      <sect2 id="dialogs=code-file">
        <title>Code (.cpp) file</title>
        <para/>
        <para>First, don't forget to have #include directives for Qt headers for any widgets you are going to reference.</para>
        <para/>
        <para>In the constructor function, connect all signals to their appropriate slots using the Qt connect() call.</para>
        <para/>
        <para>Then the easy bit; write your code.</para>
        <para/>
        <para>Finally, terminate the source file with the following</para>
        <para/>
        <programlisting>   #include "&lt;KN&gt;dlg.moc"</programlisting>
        <para/>
        <para>This is one of the files generated by the Qt MOC (Meta Object Compiler) during the make process; if you finish up with 'vtable' errors, it's probably because you forgot to include this.</para>
        <para/>
      </sect2>
    </sect1>
    <sect1 id="dialogs-updating-makefile">
      <title>Updating the Makefile</title>
      <para/>
      <para>You will need to edit file Makefile.am in the dialogs source folder before building &kappname;. Note that due to the abstruse rules of make, the lists of files should consist of a single logical line, so be careful regarding any editor options which may cause automatic insertion of line breaks. You can however use a continuation character of backslash to spread the list over multiple physical lines. There must be no character following the continuation character, not even a blank.</para>
      <para/>
      <para>- Add &lt;kn&gt;dlgdecl.ui and &lt;kn&gt;dlg.cpp to the libdialogs_a_SOURCES line</para>
      <para>- Add &lt;kn&gt;dlgdecl.ui to EXTRA_DIST</para>
      <para>- Add &lt;kn&gt;dlgdecl.cpp and &lt;kn&gt;dlgdecl.h to DISTCLEANFILES</para>
      <para>- Add &lt;kn&gt;dlg.h to NOINST_HEADERS</para>
      <para/>
      <para>Save the file, and you are ready to build &kappname;. For the first build after updating Makefile.am you should re-run 'make -f Makefile.dist', reconfigure and make. Otherwise, some make rules might not be present and compiling fails.</para>
      <para/>
      <para>That's all, simple wasn't it.</para>
      <para/>
    </sect1>
  </chapter>