Developer Jobs : Dialogs/Wizards

Lookup Column Wizard : Design Documentation

 Creation date: 2004-12-08
 Docs maintained by: jstaniek

Table of Contents      Objectives      WELCOME. Select lookup type    Pages for way1       TableOrQueryDataSource       FieldsSelection       SortOrder       ColWidth       SelectBindingColumn       EnterColumnName    Pages for way2       EnteringDataByHand       SelectBindingColumn       EnterColumnName    Implementation Notes      KDE/Kexi Classes      Data structures      Related tasks    See Also

Objectives

Lookup Column Wizard allows you to add a database relation for a single column. Basically, once such relation is defined (one-to-many), it allows user to select one of many values for a given field using some sort of combo box. The task is to deliver intelligent GUI for this wizard. This task doesn't include a code for creation the column itself.

WELCOME. Select lookup type

There are two ways of defining "many" side of this relation:

way 1. Picking an existing table or query, so their rows wil be displayed for selection

way 2. Simple version: Entering rows by hand, what creates a simple dictionary.

The 1st way is more generic, and allows to reuse once defined data schemas.

 Sequence Diagram
 WELCOME:SelectLookupType ->
    (way1)-> TableOrQueryDataSource -> FieldsSelection -> SortOrder ->
            ColWidth -> SelectBindingColumn -> EnterColumnName ->END
    (way2)->EnteringDataByHand -> SelectBindingColumn (like above) ->
           EnterColumnName (like above) ->END

Notes:

• SelectBindingColumn and EnterColumnName pages are identical for either 1st and 2nd way.

Pages for way1

TableOrQueryDataSource

• For tables/queries list, general-purpose Kexi widget should be used (not yet implemented). Only one item can be selected here.
• Unlike presented on the screenshot, do not add "tables/queries/Both" radio buttons, but tables and queries should be displayed on the list (2 columns), eg:

 Type    Name
 ----    ----
 Table   [icon]Table1
 Table   [icon]Table2
 Query   [icon]Query1

2nd column contains an icon ("table" or "query").

FieldsSelection

Inerit from KActionSelector class here to implement KexiFieldSelectionWidget class.

Note: this widget will be reused later in other Kexi areas.

SortOrder

Do not implement this page as you can see on the shot below. Use KexiTableView widget together with not-db-aware KexiTableViewData. See formeditor/connectiondialog.cpp or plugins/tables/kexialtertabledialog.cpp for example usage. Following columns should be visible:

 Field    Sorting
 -----    -------

__Field column shouldn't be editable.

Sorting column should be a combo box (just like field type combo in kexialtertabledialog), having three possible items: "No sorting" (the default), "Ascending" and "Descending".

The tableview shouldn't allow insertions.

ColWidth

Like for SortOrder page, use here KexiTableView widget together with KexiTableViewData. But this time, the table view is db-aware -- should be filled with data from a table or query selected on TableOrQueryDataSource page.

The tableview shouldn't allow data editing and insertions - only setting column width.

SelectBindingColumn

RULE: Skip this page if either:

• there's only one field in the selected lookup table/query
• or the table or query has a single-field primary key defined.

Note: currently we're not supporting bindings using more than one fields at a time.

EnterColumnName

Pages for way2

EnteringDataByHand

This page is similar ColWidth page - use here KexiTableView widget together with KexiTableViewData. But this time, the table view is not db-aware, because the values will be entered by hand.

• By default, set "Number of columns" field to 1. This value should be in a range (1..32). Use KIntNumInput class for this field.
• Create tableview with only one column and no rows. The tableview should allow row adding, deleting and editing.
• For "Number of columns" widget, on
  • focus-out event
  • and valueChanged(int) signal

update table data by adding or removing columns within it (do it by modifying KexiTableViewData). Existing rows should be preserved, if possible.

SelectBindingColumn

identical as the one for way1 (see SelectBindingColumn screenshot and it's notes)

EnterColumnName

identical as the one for way1 (see EnterColumnName screenshot and it's notes)

Implementation Notes

KDE/Kexi Classes

• Use KWizard for the wizard, use KDE widgets (e.g. KPushButton) instead of these from Qt.
• Use Kexi widgets if possible, and KexiDB API to get show required data to a user

TODO......

Data structures

• The wizard should take KexiLookupColumnData structure at input and modifies just this structure, do not create anything in the database backend. On successfull closing of KWizard (i.e . when Finish was clicked) the structure will be used to create given column data.
• You should do your best to assert the data structure always contain valid information, i.e.
• Dialog is modal, so you do not need to care about errors that can come because of concurent modification of, say, table schema. However, creation code that will use the data structure will contain required checks needed in multiuser db environment.

Related tasks

• OPTIONAL: For artists: Add graphics for wizard's pages. See here and here for templates.

See Also

• KexiDB Lookup Columns - the topic covered at database level.
• (external tutorial) Lookup Tables in Access