2 <!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" >
6 <sect1 id="designing-forms">
7 <title>Designing Forms</title>
9 <sect2 id="most-important-terms">
10 <title>Most important terms</title>
12 <glossentry id="gloss-form">
13 <glossterm>Form</glossterm>
16 A window provided for easy data entry and presentation on the
21 <glossentry id="gloss-form-data-source">
22 <glossterm>Form's data source</glossterm>
25 Database table or query providing data displayed in the
26 form. The data source is needed because forms itself are only
27 <emphasis>tools</emphasis> for displaying and entering data,
28 while tables and queries are the source of data. New, empty
29 forms have no data source assigned, so they are not displaying
30 any data from your database unless you assign a data source
35 <glossentry id="gloss-form-field">
36 <glossterm>Form field</glossterm>
39 Direct equivalent of a column in a table or query. Most frequently
40 used are fields for displaying text and numbers. Entering a new
41 value or changing the existing value of such a field causes a change
42 in the bound table or query column (after accepting the change).
46 <glossentry id="gloss-form-design">
47 <glossterm>Form design</glossterm>
50 Tasks you are performing to define the appearance and functions of
51 the form. To do this, you need to provide
52 <glossterm linkend="gloss-form-data-source">data source</glossterm>,
53 insert <glossterm linkend="gloss-form-field">form fields</glossterm>
54 of various types and place them at the appropriate location.
58 <glossentry id="gloss-form-widget">
59 <glossterm>Form widget</glossterm>
61 <para>Form's element. Main widget types are:</para>
65 Widgets displaying information, ⪚ a text box or an image box. Each
66 widget of this type can be <emphasis>bound</emphasis> to a data
67 source field (a table or a query column). Therefore, such widgets
68 are called in short <glossterm linkend="gloss-form-field">form fields</glossterm>.
73 Widgets able to perform a specified action, ⪚ a push button
74 that can close the current form. Within other applications this
75 widget type is sometimes called <firstterm>form control</firstterm>
76 because it can perform previously defined action of
77 <emphasis>controlling</emphasis> your database application's
83 Other widgets allowing to enrich a form's appearance, ⪚
84 a <quote>line widget</quote> can visually separate two form
91 <glossentry id="gloss-container-widget">
92 <glossterm>Container widget</glossterm>
95 A widget that can <emphasis>contain</emphasis> other widgets within
96 its area. For example, frame widget or tab widget are containers.
97 The form's surface itself is a container as well. A command button cannot
98 be called as container because it is not possible to insert a widget
99 inside it. In more complex cases, container widgets can be inserted
100 inside a container, so nesting is possible.
104 <screeninfo>Example container widgets</screeninfo>
107 <imagedata fileref="img/05_04_01_widget_containers.png" format="PNG"/>
110 <phrase>Example container widgets</phrase>
119 <sect2 id="forms-versus-tables">
120 <title>Forms versus tables</title>
122 In chapter <!--<a href="05_02_00_entering_data_into_tables.html">5.2</a>-->
123 5.2 you learned about how to enter data directly into tables using their
124 data sheet view. However, in many cases forms are better suited for data
130 A table can contain too many columns to display them on your
131 screen. A form can display such a data using multiple rows.
136 A form allows to visually split data <glossterm linkend="gloss-form-field">fields</glossterm>
137 into logical groups, thus increasing readability. Labels with
138 additional information can be inserted to give users more hints
139 on how to use the form or what given data <glossterm linkend="gloss-form-field">fields</glossterm> mean.
144 Command buttons can be used within forms for commonly used commands
145 so users can use forms in a similar way as a standalone applications they
150 <para>In data sheet view displaying multi-row data text
151 <glossterm linkend="gloss-form-field">fields</glossterm> or images
152 is as easy as within forms.
159 <title>Working with form design</title>
160 <para>As with table or query design, you are able to use <interface>Data View</interface>
161 and <interface>Design View</interface>. Form designing is performed in
162 <interface>Design View</interface>. We will often refer to the form design window as to
163 <interface>Form Designer</interface>.
167 <para>To create a new empty form, select
168 <menuchoice><guimenu>Insert</guimenu><guimenuitem>
169 <!--<img src="img/form_newobj.png" class="icon">-->Form</guimenuitem></menuchoice>
170 from the Menubar. Optionally, you can use
171 <menuchoice><guimenuitem>
172 <!--<img src="img/form_newobj.png" class="icon">-->New Form</guimenuitem></menuchoice>
173 command from drop-down button on the <interface>Project Navigator's</interface>
174 toolbar or <menuchoice><guimenuitem>Create Object: Form</guimenuitem></menuchoice> command from the context menu.
178 <para>A new frame will appear, you can resize the form by moving the
179 borders. The form is covered with a grid which simplifies
180 accurate positioning of the widgets.
183 <screeninfo>A window with design of a new form</screeninfo>
186 <imagedata fileref="img/05_04_03_new_empty_form.png" format="PNG"/>
189 <phrase>A window with design of a new form</phrase>
195 <para>As with table design, <interface>Form Designer</interface> provides
196 <interface>Property pane</interface>. To save some space on the screen,
197 the pane has three tabs related to the currently
202 <term>The <guilabel>Properties</guilabel> tab</term>
204 <para>Contains a list of properties for the currently selected widget.</para>
209 <!--<img src="img/property_pane_datasource_tab.png" class="icon">-->
210 The <guilabel>Data source</guilabel> tab
214 Contains properties related specifically to the <glossterm linkend="gloss-form-data-source">data source</glossterm>
215 of the currently selected widget or the form itself.
221 <!--<img src="img/property_pane_widget_tab.png" class="icon">-->
222 The <guilabel>Widgets</guilabel> tab
226 Contains a hierarchy of all widgets of the form. The list simplifies
227 widgets lookup by name and navigation between them.
233 There is information about currently selected widget's name and type displayed
234 on the first and second tab.
236 <para>Additional toolbars are also available:</para>
240 The <guilabel>Widgets</guilabel> toolbar used for inserting new widgets
246 The <guilabel>Format</guilabel> toolbar used to format form's elements (⪚
247 adjusting widget's size, grouping). Formatting commands are also available
248 in the <guimenu>Format</guimenu> menu. More about these commands can be found
249 in <xref linkend="formatmenu"/>.
250 <!--<a href="aa_05_00_menu.html#menu_format">A.6. Format Menu</a>-->
256 <sect2 id="using-the-widgets-tab">
257 <title>Using the <guilabel>Widgets</guilabel> tab</title>
259 The <guilabel>Widgets</guilabel> tab in the <interface>Property pane</interface> provides
260 a list of form widgets and their hierarchy. Each widget is presented
261 within the hierarchy beside other widgets being on the same level
262 (the same parent container). Child widgets (inside containers) are
263 presented using indented names.
265 <!--<para>In the picture below, the form (a container) contains two widgets:
266 <guilabel>groupBox2</guilabel> and <guibutton>options</guibutton> command button. In
267 turn, <guilabel>groupBox2</guilabel> (being a container itself) contains two check box
271 <screeninfo>Using the <quote>Widgets</quote> tab</screeninfo>
274 <imagedata fileref="img/05_04_04_widgets_tab.png" format="PNG"/>
277 <phrase>Using the <quote>Widgets</quote> tab</phrase>
282 Each widget has displayed its name and type. The type has also an icon
283 displayed - the same as the one displayed on the toolbar used while
284 form designing is performed.
290 Changing the current selection on the list causes appropriate selection
291 on the designed form. This allows for easier widget lookup by name and
292 easier navigation. For example, it is possible to select a widget by
293 name, and then switch to the <guilabel>Properties</guilabel> tab to change the
294 widget's properties.</para>
298 Keeping the <keycap>Ctrl</keycap> key pressed while an item on the
299 widgets list is being selected allows to select multiple widgets at a time.
300 Keeping the <keycap>Shift</keycap> key pressed allows to select entire lists
305 When widget is inserted, it is recommended to give it a reasonable name.
306 For example, <guilabel>green</guilabel> check box widget has been named specifically
307 for its meaning, using the <guilabel>Properties</guilabel> tab
308 (<guilabel>Name</guilabel> property has been used to do that). Such change
309 can make it easier to find a widget within the list.
312 <screeninfo>Naming the widget as <guilabel>green</guilabel></screeninfo>
315 <imagedata fileref="img/05_04_04_renaming_widgets.png" format="PNG"/>
318 <phrase>Naming the widget as <guilabel>green</guilabel></phrase>
326 Giving widgets reasonable names can be useful but is not mandatory. Note
327 that widget's name is a property that is not visible to the user of your form.
328 Users will only see a widget text, provided by <varname>Text</varname> property
333 <sect2 id="inserting-widgets-text-fields">
334 <title>Inserting widgets - text fields</title>
336 Let's create a form providing information about persons, i.e. a form connected
337 it with <literal>Persons</literal> table.
340 If the form being designed should present data obtained from the database,
341 you need to place appropriate <glossterm linkend="gloss-form-field">fields</glossterm>
342 on it. To do this, use the buttons on the <guilabel>Widgets</guilabel> toolbar. Each button corresponds to a single widget type.
347 Click <!--<img src="img/lineedit.png" class="icon">-->
348 <guibutton>Text Box</guibutton> button on the <guilabel>Widgets</guilabel> toolbar.
353 Click on the form surface with the <mousebutton>left</mousebutton> mouse
354 button. A new text box widget will be placed in the point where you clicked.
355 Before you release you can drag your mouse to specify a desired size for the widget.
360 If needed, move the inserted widget using drag & drop to a desired
361 position. You can resize the widget afterwards by dragging one of the
362 small boxes appearing near its corners. Note that the boxes are only
363 visible when the widget is selected. If you select another widget or the
364 form surface, the boxes disappear.
368 <para>Click the <guibutton>Text Box</guibutton> toolbar button again and click
369 on the form surface to insert another widget. Repeat this action once
370 again until you get three text boxes inserted in your form. For sake of
371 simplicity we will limit ourselves to three data
372 <glossterm linkend="gloss-form-field">fields</glossterm>.
380 There is a context menu available in form's design mode, activated by a
381 <mousebutton>right</mousebutton> mouse button click the desired widget
382 or the form's surface. The menu offers commands like
383 <!--<img src="img/editcut.png" class="icon">--><guimenuitem>Cut</guimenuitem>,
384 <!--<img src="img/editcopy.png" class="icon">--><guimenuitem>Copy</guimenuitem>,
385 <!--<img src="img/editpaste.png" class="icon">--><guimenuitem>Paste</guimenuitem>,
386 <!--<img src="img/editdelete.png" class="icon">--><guimenuitem>Delete</guimenuitem>
387 and other, more complex. Many of the commands are also provided in the
388 <guilabel>Menubar</guilabel>, usually <guimenuitem>Edit</guimenuitem>.
389 Keyboard shortcuts are also available for these commands. Some of the
390 commands are only available for certain types of widgets.
395 The commands <guimenuitem>
396 <!--<img src="img/editcut.png" class="icon">-->Cut</guimenuitem>,<guimenuitem>
397 <!--<img src="img/editcopy.png" class="icon">-->Copy</guimenuitem> and <guimenuitem>
398 <!--<img src="img/editpaste.png" class="icon">-->Paste</guimenuitem>
399 makes it possible to move or copy widgets between forms, even between separate
405 Holding the <keycap>Ctrl</keycap> key down while clicking a widget allows to select
411 Instead of using <guimenuitem>
412 <!--<img src="img/editcopy.png" class="icon">-->Copy</guimenuitem>
414 <!--<img src="img/editpaste.png" class="icon">-->Paste</guimenuitem>
415 commands, to duplicate a widget within the same form you can hold down the
416 <keycap>Ctrl</keycap> key while moving the widget. After the <keycap>Ctrl</keycap>
417 key is released, the dragged widget will not be moved but copied in the new location.
424 <sect2 id="assigning-data-sources">
425 <title>Assigning data sources</title>
427 The <glossterm linkend="gloss-form-field">fields</glossterm> you inserted
428 have no <emphasis>data source</emphasis> assigned yet,
429 so these are not able to display information from the database. To assign data
430 source, use the <!--<img src="img/database.png" class="icon">-->
431 <guilabel>Data Source</guilabel> tab of the <interface>Property pane</interface>.
434 The very first step is to specify the <glossterm linkend="gloss-form-data-source">form's data source</glossterm>,
435 i.e. a place the displayed data will be fetched from. As mentioned above, you
436 will use table <literal>persons</literal> as a
437 <glossterm linkend="gloss-form-data-source">data source</glossterm>
442 <para>Click on the form's surface, as you will alter its properties.</para>
446 Switch to the <!--<img src="img/database.png" class="icon">-->
447 <guilabel>Data Source</guilabel> tab and enter <literal>persons</literal>
448 table name in the <guilabel>Form's data source</guilabel> drop down list.
449 Alternatively, you can select this name from the drop down list.
452 <screeninfo>Entering <glossterm linkend="gloss-form-data-source">form's data source</glossterm> name</screeninfo>
455 <imagedata fileref="img/05_04_05_entering_form_data_source.png" format="PNG"/>
458 <phrase>Entering <glossterm linkend="gloss-form-data-source">form's data source</glossterm> name</phrase>
465 You have assigned <glossterm linkend="gloss-form-data-source">form's data source</glossterm>. Now you need to do specify
466 widget's data source.
470 <para>Click the first text field widget at the top of the form.</para>
474 In the <!--<img src="img/database.png" class="icon">--><guilabel>Data Source</guilabel>
475 tab of the property pane enter field name <varname>name</varname> in the
476 <emphasis>Widget's data source</emphasis> drop down list. Alternatively, you can select
477 this name from the drop down list.
480 <screeninfo>Entering widget's data source name</screeninfo>
483 <imagedata fileref="img/05_04_05_entering_text_field_data_source.png" format="PNG"/>
486 <phrase>Entering widget's data source name</phrase>
492 <para>Click on next text field widget and enter <varname>surname</varname> as the data source.</para>
496 Enter data sources for <varname>street</varname>, <varname>house_number</varname>
497 and <varname>city</varname> text <glossterm linkend="gloss-form-field">fields</glossterm>
503 You can now save the form's design (this is not mandatory to test the
504 form in action). To save, click the
505 <!--<img src="img/filesave.png" class="icon">-->
506 <guilabel>Save object changes</guilabel> toolbar button or use the
507 <menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap><keycap>S</keycap></keycombo></shortcut>
508 <guimenu>File</guimenu><guimenuitem>
509 <!--<img src="img/filesave.png" class="icon">-->Save</guimenuitem></menuchoice>
510 menu command. Upon saving you will be asked for entering the form's name. Enter
511 <literal>Persons</literal> as caption and click the <guibutton>OK</guibutton>
512 button. The form's name will be filled automatically.
515 This is the right moment for testing your form. Click the <!--<img src="img/state_data.png" class="icon">-->
516 <guibutton>Switch to data view</guibutton> toolbar button. Unless you made a
517 mistake while entering data sources, you should see
518 <glossterm linkend="gloss-form-field">form's fields</glossterm> filled
519 with data from the <literal>persons</literal> table.
522 <screeninfo>The <literal>Persons</literal> form in data view after inserting text fields and assigning data sources</screeninfo>
525 <imagedata fileref="img/05_04_06_form_with_text_fields.png" format="PNG"/>
528 <phrase>The <literal>Persons</literal> form in data view after inserting text fields and assigning data sources</phrase>
536 If you want to remove widget's <glossterm linkend="gloss-form-data-source">data source</glossterm>
537 assignment for a form widget, you can use <!--<img src="img/clear_left.png" class="icon">-->
538 <guibutton>Clear widget's data source</guibutton> button near
539 the <guilabel>Widet's data source</guilabel> drop down list. Similarly, you can use the
540 <!--<img src="img/clear_left.png" class="icon">-->
541 <guibutton>Clear form's data source</guibutton> button near the
542 <guilabel>Form's data source</guilabel> drop down list.
547 Use the <!--<img src="img/goto.png" class="icon">-->
548 <guibutton>Go to selected form's data source</guibutton> button to select
549 appropriate table or query in the <interface>Project Navigator</interface>,
550 so you can quickly open a table or query being the
551 <glossterm linkend="gloss-form-data-source">data source</glossterm>
556 <!-- TODO: mention about creating Auto Fields by using drag & drop -->
560 <sect2 id="inserting-text-labels">
561 <title>Inserting text labels</title>
563 To make it easier for the form's user to identify the meaning of every field
564 widget, these should have added text labels with appropriate titles. To
565 create text labels the <!--<img src="img/label.png" class="icon">-->
566 <literal>Label</literal> widget is used.
569 Insert three text label widgets onto the form, placing them on the left
570 side of the text fields (or on the right hand if your operating system
571 uses right-to-left layout). On inserting a new label, a text cursor
572 appears at the location where you can enter the desired title. Enter consecutively:
573 <literal>Name</literal>, <literal>Surname</literal> and <literal>Street</literal>. Additionally,
574 on the top of the form insert another label displaying name of the form,
575 i.e. <literal>Persons</literal>. Enlarge this label's size and and increase the font size using
576 <!--<a href="aa_00_00_menu.html#menu_format_font">-->
577 <menuchoice><guimenu>Format</guimenu><guimenuitem>Font...</guimenuitem></menuchoice>
582 <screeninfo>Ready to use form after adding text labels</screeninfo>
585 <imagedata fileref="img/05_04_06_form_with_labels.png" format="PNG"/>
588 <phrase>Ready to use form after adding text labels</phrase>
595 <title>Actions</title>
597 An <literal>Action</literal> is a single activity isolated in the application,
598 available for the user to execute. It can also be executed automatically as a
599 reaction for a given event (⪚ after opening a form).
602 <sect3 id="assigning-actions-to-form-buttons">
603 <title>Assigning actions to form buttons</title>
605 Many actions can be assigned to form button. The assigned action is executed
606 after button is clicked.
608 <para>To assign action:</para>
611 <para>Switch to form's <interface>Design view</interface> if you have not done yet.</para>
615 Select the existing button widget by clicking on it or put a new button
616 widget onto the form. If you inserted a new button, enter its title and
617 press <keycombo action="press"><keycap>Enter</keycap></keycombo> key.
622 Click the button widget with the <mousebutton>right</mousebutton> mouse
623 button to display the context menu.
628 From the context menu select
629 <!--<img src="img/form_action.png" class="icon">-->
630 <guimenuitem>Assign action...</guimenuitem> command.
635 An <guilabel>Assigning Action to Command Button</guilabel> dialog window
636 will appear presenting a list of available actions. One of the actions
637 is selected if the widget already has action assigned. Otherwise the
638 <guilabel>Action type</guilabel> drop down list has the <guilabel>No type</guilabel>
644 From the <guilabel>Action type</guilabel> drop down list select
645 <guilabel>Application</guilabel> item. Available application-wide actions
650 <para>Select one of the actions on the list (⪚ <guilabel>Delete Row</guilabel>).</para>
654 Click the <guibutton>OK</guibutton> button or press
655 the <keycombo action="press"><keycap>Enter</keycap></keycombo> key to
656 accept your selection.
661 <screeninfo>Assigning <guilabel>Delete Row</guilabel> action to a form's button</screeninfo>
664 <imagedata fileref="img/05_04_07_assigning_action_to_button.png" format="PNG"/>
667 <phrase>Assigning <guilabel>Delete Row</guilabel> action to a form's button</phrase>
672 After switching to the form's <emphasis>data view</emphasis> you can try
673 whether the action works. For example, if you assigned <guilabel>Delete Row</guilabel>
674 action, clicking the button, the current database row will be deleted, similarly
675 to executing <menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap><keycap>Delete</keycap></keycombo></shortcut><guimenu>Edit</guimenu><guimenuitem>Delete Row</guimenuitem></menuchoice>
676 menu command (depending on your settings you may be asked to confirm the removal).
683 To remove an action assignment, select <guilabel>No type</guilabel> item from
684 the <guilabel>Action type</guilabel> drop down list of the
685 <guilabel>Assigning Action to Command Button</guilabel> dialog window.
690 Actions only work in the form's <emphasis>data view</emphasis>. Not every
691 action's assignment is reasonable. For example, the
692 <guimenuitem>Font...</guimenuitem> action is available in data view, but
693 only if you have a widget selected in the <interface>Design view</interface>. If you
694 make changes to the font settings the changes are applied to the text
695 of that selected widget.
703 <sect2 id="widget-layouts">
704 <title>Widget layouts</title>
706 In most cases form widgets should be conveniently arranged and aligned.
707 Positioning, aligning and resizing widgets by hand is not easy and these
708 parameters are not adjusted when the user resizes the form. In fact the
709 situation is even worse because you cannot assume a given form requires
710 a given space because users have different font sizes and display resolutions.
714 The following example presents a form where text fields and labels were
715 placed by hand. Some of them cannot fit in the form's window.
718 <screeninfo>An example form with widgets that cannot not fit in the window</screeninfo>
721 <imagedata fileref="img/05_04_08_form_no_fit.png" format="PNG"/>
724 <phrase>An example form with widgets that cannot not fit in the window</phrase>
729 Using special tool called widget layouts can help to automatically lay
730 out the form widgets. Widget layout is an action of grouping two or more
731 widgets so these are well positioned and have appropriate sizes.
734 Using layout in a form improves alignment. Moreover, its space is
735 better used. Text fields are closer to each other, spacing is constant.
738 <screeninfo>Example form with layout used</screeninfo>
741 <imagedata fileref="img/05_04_08_form_well_fit.png" format="PNG"/>
744 <phrase>Example form with layout used</phrase>
748 <para>There are two methods to create widget layout.</para>
752 Select two or more widgets that should be placed in a common layout,
753 and select one of the layout types from the context menu item
754 <!--<a href="aa_00_00_menu.html#menu_format_layout">-->
755 <guilabel>Layout Widgets</guilabel>
761 Click a container widget (or a form surface itself), where widgets are
762 inserted and select one of the layout types from the context menu item
763 <!--<a href="aa_00_00_menu.html#menu_format_layout">-->Layout Widgets
765 All widgets existing within the container or within the
766 form, being on the same level will be put into a single common layout.
771 In each of these cases you can also use
772 <menuchoice><guimenu>Format</guimenu><guimenuitem>Layout Widgets</guimenuitem></menuchoice>
776 <screeninfo>Selecting widgets that will be put into a layout</screeninfo>
779 <imagedata fileref="img/05_04_08_form_layout_selecting.png" format="PNG"/>
782 <phrase>Selecting widgets that will be put into a layout</phrase>
787 <screeninfo>Four widgets are selected</screeninfo>
790 <imagedata fileref="img/05_04_08_form_layout_selected.png" format="PNG"/>
793 <phrase>Four widgets are selected</phrase>
798 <screeninfo>Using the context menu for putting the widgets into a grid layout</screeninfo>
801 <imagedata fileref="img/05_04_08_form_layout_popup.png" format="PNG"/>
804 <phrase>Using the context menu for putting the widgets into a grid layout</phrase>
809 Widget layout is presented in the design view using a blue, green or
810 red box drawn with a broken line. This line is displayed only in the
814 <screeninfo>Widgets within a grid layout</screeninfo>
817 <imagedata fileref="img/05_04_08_form_layout_grid.png" format="PNG"/>
820 <phrase>Widgets within a grid layout</phrase>
824 <para>Besides the grid type, there are other widget layout types.</para>
827 <term>vertical</term>
829 <para>Vertical widget layout</para>
831 <screeninfo>Vertical widget layout</screeninfo>
834 <imagedata fileref="img/05_04_08_form_layout_vertical.png" format="PNG"/>
837 <phrase>Vertical widget layout</phrase>
844 <term>horizontal</term>
846 <para>Horizontal widget layout</para>
848 <screeninfo>Horizontal widget layout</screeninfo>
851 <imagedata fileref="img/05_04_08_form_layout_horizontal.png" format="PNG"/>
854 <phrase>Horizontal widget layout</phrase>
860 <!-- TODO podzia poziomy / pionowy
861 <br><img src="img/05_04_08_form_layout_vertical_splitter.png">
863 <br><img src="img/05_04_08_form_layout_horizontal_splitter.png">
868 <sect3 id="springs-in-widget-layouts">
869 <title>Springs in widget layouts</title>
871 A <emphasis>spring</emphasis> in widget layouts is a special, invisible element allowing
872 to adjust widget's position and size within layouts. Such a spring
873 stretches or squeezes a widget on the right, top, bottom or left hand,
874 so it can have desired size and position.
876 <para>To use a spring:</para>
880 Select <!--<img src="img/spring.png" class="icon">-->spring icon on the
881 <guilabel>Widgets</guilabel> toolbar.
885 <para>Click on a selected point of the form to insert the spring.</para>
889 For the following example, the spring has been inserted on the left
890 hand of the text label "Persons". The label is thus displayed on the
891 right hand of the form. To make the spring work, it has been put into
892 a common horizontal layout with the label.
895 <screeninfo>Horizontal layout containing a spring and a text label</screeninfo>
898 <imagedata fileref="img/05_04_08_form_spring.png" format="PNG"/>
901 <phrase>Horizontal layout containing a spring and a text label</phrase>
906 To make springs work you need to create a global widget layout, i.e. a
907 layout for the form itself. Then, springs can use edges of the form as
908 a boundary for expanding.
913 TODO: The entire text in this section is built around a screenshot
914 example, so it's commented out for now.
916 <sect3 id="advanced-widget-layouts">
917 <title>Advanced widget layouts</title>
919 Widget layouts can be combined (or nested). On the following example
920 you can identify two nested layouts:
925 Horizontal layout with a spring, aligning the <literal>Persons</literal>
926 text label to the right.
930 <para>Grid layout grouping widgets on the whole form.</para>
934 <screeninfo>Two widget layouts combined: horizontal layout inside of a grid layout</screeninfo>
937 <imagedata fileref="img/05_04_08_form_advanced_layout.png" format="PNG"/>
940 <phrase>Two widget layouts combined: horizontal layout inside of a grid layout</phrase>
945 The horizontal layout is treated in the example as a single widget by
946 the grid layout - it takes exactly one <quote>cell</quote> of the grid.
947 After opening a form designed this way in the data view, you can notice
948 (by resizing the form) that:
953 <literal>Persons</literal> text label thanks to the spring used is constantly
954 aligned to the to the right side of the form.
959 Text fields take all of the available width thanks to putting them
960 into the grid layout.
965 All the form's widgets are pushed to the top thanks to the spring
966 used at the bottom of the form.
971 <screeninfo>The form using the two layouts displayed in data view</screeninfo>
974 <imagedata fileref="img/05_04_08_form_advanced_layout_view.png" format="PNG"/>
977 <phrase>The form using the two layouts displayed in data view</phrase>
983 <sect3 id="removing-widget-layouts">
984 <title>Removing widget layouts</title>
986 To remove widget layout without removing widgets, perform one of
992 Click with the <mousebutton>right</mousebutton> mouse button on
993 the layout's border and select <guimenuitem>Break Layout</guimenuitem>
994 command from the context menu.
999 Click with the <mousebutton>left</mousebutton> mouse button on
1000 the layout's border and select
1001 <menuchoice><guimenu>Format</guimenu><guimenuitem>Break Layout</guimenuitem></menuchoice>
1008 Removing widget layout using the <guimenuitem>Break Layout</guimenuitem>
1009 command will not remove widgets contained in the layout. If you want to
1010 remove the widgets as well, just select the layout by clicking on its
1011 border and press <keycap>Delete</keycap> key or use
1012 <menuchoice><guimenu>Edit</guimenu><guimenuitem>
1013 <!--<img src="img/editdelete.png" class="icon">-->Delete</guimenuitem></menuchoice>
1014 menu command or context menu command.
1019 <sect3 id="size-policies-for-widgets-within-a-layout">
1020 <title>Size policies for widgets within a layout</title>
1022 Instead of setting a fixed size for your widgets, in &kexi; you can
1023 choose between various widget's size policies. A <emphasis>size policy</emphasis>
1024 is a flexible strategy for controlling how a widget is stretched (or shrunk)
1025 depending on other neighbouring widgets and space available within the form.
1028 After putting widgets into a <emphasis>layout</emphasis>, typically each widget
1029 gets a proportional (<guilabel>Preferred</guilabel>) size policy. These widgets
1030 will be automatically resized with preferred settings, depending on their
1031 type and size of the entire layout itself. For example, three buttons put
1032 into the horizontal layout will be resized to fit their visible text.
1034 <para>For each widget inserted into the form, there are settings for size policy
1035 available in the <interface>Property Editor</interface>. The settings are presented
1036 as a group of properties called <guilabel>Size Policy</guilabel>.
1039 <screeninfo>A group of properties for defining a widget's size policy</screeninfo>
1042 <imagedata fileref="img/05_04_09_size_policy_properties.png" format="PNG"/>
1045 <phrase>A group of properties for defining a widget's size policy</phrase>
1049 <para>This group of properties contains:</para>
1052 <term><guilabel>Horizontal Size Policy</guilabel></term>
1054 <para>defining horizontal size of the widget,</para>
1058 <term><guilabel>Vertical Size Policy</guilabel></term>
1060 <para>defining vertical size of the widget,</para>
1064 <term><guilabel>Horizontal Stretch</guilabel></term>
1067 defining strength of activity of the
1068 <guilabel>Horizontal Size Policy</guilabel>,
1073 <term><guilabel>Vertical Stretch</guilabel></term>
1076 defining strength of activity of the
1077 <guilabel>Vertical Size Policy</guilabel>
1084 <title>Values of size policies</title>
1086 The following values are available in the drop down list for
1087 <guilabel>Horizontal Size Policy</guilabel> and
1088 <guilabel>Vertical Size Policy</guilabel> properties visible
1089 in the <interface>Property Editor</interface>:
1093 <term><guilabel>Fixed</guilabel></term>
1096 this value means that the widget cannot be automatically resized; it
1097 should maintain the constant size defined at design time (width or height),
1102 <term><guilabel>Minimum</guilabel></term>
1105 this value means that the original size of the widget is set as minimal
1106 allowed, it is sufficient and there is no need for expanding the widget,
1107 but the widget will be expanded if needed. This type of policy can be used
1108 to force the widget to be expanded to the whole width or height, especially
1109 if you set a stretch value greater than 0.
1112 <screeninfo>Text field and two buttons within a grid layout (Minimum horizontal size policy is set for both buttons, so these are slightly wider than needed)</screeninfo>
1115 <imagedata fileref="img/05_04_09_size_policy_minimum.png" format="PNG"/>
1118 <phrase>Text field and two buttons within a grid layout (Minimum horizontal size policy is set for both buttons, so these are slightly wider than needed)</phrase>
1125 <term><guilabel>Maximum</guilabel></term>
1128 this value means that the original size of the widget is set as maximum
1129 allowed and can be decreased without breaking the widget's usability
1130 and readability if other widgets need more space,
1135 <term><guilabel>Preferred</guilabel></term>
1138 this value means that the original size of the widget is the best and
1139 preferred; the widget can be shrunk or expanded however and it
1143 <screeninfo>Text field and two buttons within a grid layout (Preferred horizontal size policy is set for both buttons)</screeninfo>
1146 <imagedata fileref="img/05_04_09_size_policy_preferred.png" format="PNG"/>
1149 <phrase>Text field and two buttons within a grid layout (Preferred horizontal size policy is set for both buttons)</phrase>
1156 <term><guilabel>Expanding</guilabel></term>
1159 this value means that the original size of the widget is reasonable but
1160 the widget can be also shrunk; it can be expanded as well to take
1161 as much space as possible,
1166 <term><guilabel>Minimum Expanding</guilabel></term>
1169 this value means that the original size of the widget is allowed; it
1170 can be expanded to take as much space as possible,
1175 <term><guilabel>Ignored</guilabel></term>
1178 this value means that the original size of the widget is ignored; the
1179 widget can be expanded to take as much space as possible but other
1180 widgets usually will not allow for that
1186 Different widget types have various default size policies; for example,
1187 button widgets have default size policy set to <guilabel>Minimum</guilabel> (in both directions),
1188 while text field widgets have vertical size policy set to <guilabel>Fixed</guilabel>.
1191 The most frequently used size policies are <guilabel>Preferred</guilabel>,
1192 <guilabel>Minimum</guilabel> and <guilabel>Maximum</guilabel>.
1197 <title>Vertical and horizontal stretch</title>
1199 The <guilabel>Vertical Stretch</guilabel> and <guilabel>Horizontal Stretch</guilabel>
1200 properties accept integer values greater than or equal to 0. These properties allow to fine-tune the
1201 behavior of size policies. The default value for the properties is 0.
1202 A higher value of the stretch means that the widget will be expanded
1203 more than widgets for which a lower stretch value is set. <!--For example,
1204 the following image presents two buttons where the first button has
1205 Vertical Stretch set to 0 and the second button has Vertical Stretch
1209 <screeninfo>Size of button widgets affected by setting Vertical Stretch property of the second button to 1</screeninfo>
1212 <imagedata fileref="img/05_04_09_size_policy_vertical_stretch.png" format="PNG"/>
1215 <phrase>Size of button widgets affected by setting Vertical Stretch property of the second button to 1</phrase>
1223 <sect2 id="setting-widgets-size-and-position-by-hand">
1224 <title>Setting widgets size and position by hand</title>
1225 <para>In case when your form has no main layout set for auto-positioning and
1226 auto-resizing its widgets, you will probably want to modify the position and size of widgets so the form can look cleaner and be easier to use. The &kexi; form
1227 designer simplifies this task by offering the following groups of commands:
1232 Adjusting sizes of selected widgets. The commands are available in the
1233 <menuchoice><guimenu>Format</guimenu><guisubmenu>Adjust Widgets Size</guisubmenu></menuchoice>
1234 submenu of the menubar and in the
1235 <menuchoice><guisubmenu>Adjust Widgets Size</guisubmenu></menuchoice>
1236 submenu of the context menu. The toolbar's drop down
1237 button <!--<img src="img/aogrid.png" class="icon">--><guibutton>Adjust Widgets Size</guibutton>
1242 <term><!--<img src="img/aofit.png" class="icon">--><guilabel>To Fit</guilabel></term>
1245 The size of the selected widgets will be altered so each widget will be
1246 resized to its preferred size and its contents; for example, a text
1247 label's size will be changed to fit its text. The position of the widgets
1248 will not be changed.
1253 <term><!--<img src="img/aogrid.png" class="icon">--><guilabel>To Grid</guilabel></term>
1256 The size of the selected widgets will be altered so each widget's corner
1257 will be placed on the form's (or other container's) grid point.
1258 The widget's position can be slightly altered.
1263 <term><!--<img src="img/aoshortest.png" class="icon">--><guilabel>To Shortest</guilabel></term>
1266 The height of the selected widgets will be altered so that each of them
1267 will have the same height as the shortest one. The position of the widgets
1268 will not be changed.
1273 <term><!--<img src="img/aotallest.png" class="icon">--><guilabel>To Tallest</guilabel></term>
1276 The height of the selected widgets will be altered so that each of them
1277 will have the same height as the tallest one. The position of the widgets
1278 will not be changed.
1283 <term><!--<img src="img/aonarrowest.png" class="icon">--><guilabel>To Narrowest</guilabel></term>
1286 The width of the selected widgets will be altered so that each of them
1287 will have the same height as the narrowest one. The position of the
1288 widgets will not be changed.
1293 <term><!--<img src="img/aowidest.png" class="icon">--><guilabel>To Widest</guilabel></term>
1296 The width of the selected widgets will be altered so that each of them
1297 will have the same height as the widest one. The position of the widgets
1298 will not be changed.
1306 Aligning positions of the selected widgets. The commands are available
1308 <menuchoice><guimenu>Format</guimenu><guisubmenu>Align Widgets Position</guisubmenu></menuchoice>
1309 submenu of the menubar and in the
1310 <menuchoice><guisubmenu>Align Widgets Position</guisubmenu></menuchoice>
1311 submenu of the context menu. The toolbar's drop
1312 down button <!--<img src="img/aoleft.png" class="icon">-->
1313 <guibutton>Align Widgets Position</guibutton> is also available.
1317 <term><!--<img src="img/aoleft.png" class="icon">--><guilabel>To Left</guilabel></term>
1320 All the selected widgets' left positions will be moved to the
1321 position of the leftmost widget's left edge.
1326 <term><!--<img src="img/aoright.png" class="icon">--><guilabel>To Right</guilabel></term>
1329 All the selected widgets' right positions will be moved to the
1330 position of the rightmost widget's right edge.
1335 <term><!--<img src="img/aotop.png" class="icon">--><guilabel>To Top</guilabel></term>
1338 All the selected widgets' top positions will be moved to the
1339 position of the uppermost widget's upper edge.
1344 <term><!--<img src="img/aobottom.png" class="icon">--><guilabel>To Bottom</guilabel></term>
1347 All the selected widgets' bottom positions will be moved to the
1348 position of the bottommost widget's bottom edge.
1353 <term><!--<img src="img/aopos2grid.png" class="icon">--><guilabel>To Grid</guilabel></term>
1356 All the selected widgets' top-left corners will be moved so that
1357 they are positioned in the nearest grid point.
1362 <para>None of the above commands resizes the widgets.</para>
1366 There are also additional commands available:
1367 <!--<img src="img/raise.png" class="icon">--><guimenuitem>Bring Widget to Front</guimenuitem>
1368 (i.e. above all other widgets) and
1369 <!--<img src="img/lower.png" class="icon">--><guimenuitem>Send Widget to Back</guimenuitem> (i.e. below all
1370 other widgets). These two commands are rarely used, as it is not
1371 common to place one widget on top of an other (except when a
1372 container widget contains other widget inside). Also note that clicking
1373 a widget with a mouse button is enough to bring the widget to front.
1377 <sect2 id="setting-the-tab-order">
1378 <title>Setting the tab order</title>
1380 A widget's focus determines that widget's activity available using keyboard.
1381 Focus is related to widgets displayed in the form's data view. Exactly one
1382 form widget can have focus at the same time. The most frequent use of focus
1383 is text entry (when a given text field is active, i.e. it is focused).
1384 An other example is a button widget - when focused, it is possible to
1385 <quote>press</quote> it using the <keycombo action="press"><keycap>Enter</keycap></keycombo>
1386 or <keycombo action="press"><keycap>Space</keycap></keycombo> key instead of a mouse button.
1389 There are a few methods of making the widgets active (moving the focus
1390 to the widget): clicking with a mouse button, rotating the mouse wheel
1391 over the widget, or using the <keycombo action="press"><keycap>Tab</keycap></keycombo>
1392 key. The latter method is often used because of its speed and convenience
1393 for users. Availability of the focusing methods is controlled by
1394 <guilabel>Focus Policy</guilabel> property of a given widget.
1397 There is a relationship between focusing (activating) widgets using <keycombo action="press"><keycap>Tab</keycap></keycombo>
1398 key and tab order setting of a form. After pressing the <keycombo action="press"><keycap>Tab</keycap></keycombo> key, the
1399 next widget should be focused, so the form should know about the tab order.
1401 <para>To alter tab order for a form's widget:</para>
1404 <para>Switch to design view of the form.</para>
1408 Execute <menuchoice><guimenu>Edit</guimenu><guimenuitem>Edit Tab Order...</guimenuitem></menuchoice>
1409 menu command. The <guilabel>Edit Tab Order</guilabel> dialog will appear with settings for this form.
1412 <screeninfo>A window for editing tab order for a form</screeninfo>
1415 <imagedata fileref="img/05_04_11_tab_stop_dialog.png" format="PNG"/>
1418 <phrase>A window for editing tab order for a form</phrase>
1423 The window contains a list with two columns: the first column displays
1424 widget names, the second - types of the widgets. To make it easier to
1425 recognize meaning of the names and types for the user, icons related
1426 to the types are also displayed. The list contains only widgets having
1427 focus policy allowing to use the <keycap>Tab</keycap> key. The window
1428 allows you to change the tab order or set the automatic tab order.
1432 <para>To change tab order, either:</para>
1436 Click a selected widget name in the widgets list and drag it
1437 to a desired position (up or down) using the mouse.
1442 Click a selected widget name on the widgets list and use
1443 <guibutton>Move Up</guibutton> or <guibutton>Move Down</guibutton>
1444 buttons, to move the widgets to a desired position.
1449 Click the <guilabel>Handle tab order automatically</guilabel> check box to set the
1450 automatic tab order for the form. If this option has been switched
1451 on, any changes made to the list of widgets by hand are not taken
1452 into account - &kexi; will be handling the tab orders on its own.
1453 The automatic ordering means that the top-left widget will be focused
1454 first (or the top-right if your operating system uses right-to-left
1455 layout), and the order comes from the left to right (from the right
1456 to left, respectively) and from the top to bottom.
1459 <screeninfo>Automatic tab order for a form</screeninfo>
1462 <imagedata fileref="img/05_04_11_auto_tab_stop.png" format="PNG"/>
1465 <phrase>Automatic tab order for a form</phrase>
1474 Click the <guibutton>OK</guibutton> button to accept the changes or <guibutton>Cancel</guibutton> button to dismiss