Screen scaffolding: controls

Control Hierarchy

Root Control: Usually, the first Pagecontrl (tab), GroupBox (grp), User contrl (uco), or Panel (pnl). Sometimes, especially with inheritance of the forms, this does not work. So you can set the attribute RootControl=true for the control that you want to be the root. (this behaviour is implemented in Ict.Tools.CodeGeneration.TCodeStorage.GetRootControl)

Detail: if you have the word Detail in front of a control name, just after the control prefix, this means that the control belongs to the detail table.

grdDetails and pnlDetails are special controls which have special meaning for disabling the detail controls etc

Layout of Controls

• use Dock=Fill, or Dock=Top, or Dock=Bottom
  • if you use a Dock attribute for each control in a container, then it would not use TableLayoutPanel, which might improve the behaviour on Mono (Mono does not cope well with TableLayoutPanel at the moment, Mono 2.4).
• use Align=right to right-align a control (in the TableLayoutPanel's column that it is in).
  • By default, all controls are left-aligned, except for the Labels of controls that are auto-generated, those are right-aligned automatically.
• use Width=200 for setting the width of eg a txt control
• use Panels (pnl) to group controls
• by default, the controls are arranged vertically (each control below the previous control)
• to have the controls in one row, use ControlsOrientation = horizontal
• to arrange controls in a grid, use several RowX, RowY, etc as sub elements of Controls; the elements of each row are arranged horizontally.
• use ColSpan=2 to span a control over two columns
• Label sets the label for the control, otherwise it is built from the control name, without prefix
• NoLabel=true will generate the control without a label
• ReadOnly=true will make a control read-only and also prevents the cursor from jumping into the control if the user 'tabs' through the screen with the <TAB> key.
• Enabled=false will disable the control. This is useful for prototyping etc. Otherwise, you should link the control with an action, and disable the action depending on the state of the screen

Different Sizes for Mono/other languages

Mono has quite some problems with the TableLayoutManager and AutoSize controls at the moment (Mono 2.4).

As well, for other languages the labels of controls might be longer, and we need different sizes for controls.

Therefore, you can create for each screen an inherited yaml file, and just define the height and width in pixels. eg, see Client/lib/MFinance/gui/UC_GLTransactions.en.yaml; you need to set the GUI language you want to compile for in the OpenPetra.build.config file.

Attributes for controls on report screens

• ParameterName: will use the given name for the parameters that are sent to the server; otherwise it will be built from the control name
• ParameterValue: for radio buttons, assign the value that should be set if this option is selected; otherwise it will be built from the control name, or from the OptionalValues list
• NoParameter=true: will ignore the control, eg the ledger name text field is read-only, and is only for information

Control Types

Container Controls

General

• pnl: Panel. Container for any number of any Controls. Use this to logically group controls. Note: a Panel is not visible, unless a 'BackColour' is assigned.
• grp: GroupBox. Container for any number of any Controls. Similar to Panel, but it is visible: it draws a border around its containted controls and displays a title.
• tab: Tab Control. Container for any number of TabPages (tpg). Cannot contain any other kind of Control!
  • DragTabPageEnabled: allow rearranging the order of TabPages (default: true)
  • ShowToolTips: allows showing of ToolTips on the headers of the TabPages (default: false)
  • if LoadPagesDynamically is true, the Generator creates code that dynamically loads a UserControl for TabPages that have 'LoadPageDynamically' set to true. That code is only executed when the TabPage is switched to for the first time. Using this facility, a programmer can improve the load time of a form that has many controls on many TabPages! (default=false)
• tpg: TabPage of a Tab Control. Container for any number of any Controls. Similar to Panel, but has the appearance of a Tab and has a title.
  • ToolTip: defines ToolTip text that should be shown on the header of the TabPage. This is only shown if 'ShowToolTips' is set to true for the TabControl!
  • if LoadPageDynamically is true and 'LoadPagesDynamically' of the TabControl is true as well, the Generator creates code that dynamically loads a UserControl that is the only Control on this TabPage. DynamicControlType needs to be specified in this case. (default=false)
  • DynamicControlType specifies the UserControl that should get dynamically loaded. Only works if 'LoadPageDynamically' of the TabPage is true as well! See example for 'UserControl' for the value. Example:

       tpgAddresses:
           LoadPageDynamically: true
           DynamicControlType: Ict.Petra.Client.MCommon.TUCPartnerAddresses

• uco: UserControl. UserControls can be understood as 'sub-forms' or simply parts of a screen whose layout is specified separately from the screen.
  • needs attribute 'Type' with the value containing the full namespace for the control, e.g.

       ucoPersonnelTabSet:
           Type: Ict.Petra.Client.MPartner.Gui.TUC_PartnerEdit_PersonnelTabSet

Specialised

• spt: SplitContainer. Divides a part of the screen either horizontally or vertically and shows a 'Splitter line' between them. The user can 'drag' the 'Splitter line' with the mouse and give more or less space to controls on either side of the line.
  • SplitterOrientation. Supported values are: 'vertical', 'horizontal'.
  • SplitterDistance specified the Width or Height of the first Panel in pixels.
  • Panel1 and Panel2 refer to one control only at the moment.
• rgr: RadioButton group.
  • Can contain several other Controls in 'Controls' list, which will create RadioButtons with the Controls for each item.
  • Alternatively it can just contain text in value 'OptionalValues', which will create RadioButtons for each text.
• rng: Range. Used for entering two values that define a range.
  • this is basically a special Panel.

Basic Controls

Edit Controls

• txt: TextBox. A normal edit field (but see 'Type' below for different behaviour).
  • use TextAlign to align text in the TextBox. Supported values are: Left, Right, Center (default=Left).
  • use CharacterCasing to make the text typed appear in a certain character casing. Supported values are: 'Upper' (for all-uppercase), 'Lower' (for all-lowercase), 'Normal' (for showing the text as typed). Default=Normal.
  • use PasswordEntry=true to prevent any characters that are typed from being shown and show a mask symbol instead of the characters (default=false).
  • use Multiline=true to allow text entry in more than one line of text. To determine the height of the TextBox, use 'Height'. Make sure you assign 'Height', otherwise the TextBox will still appear in its default height, which makes it appear single-line (default=false).
    • if 'Multiline' is true, use ScrollBars to determine which scrollbars should appear. Supported values are: 'Horizontal', 'Vertical', 'Both', 'None' (default=none).
    • if 'Multiline' is true, use WordWarp=false to automatically scroll horizontally when the user types past the right edge of the control (default=true).
  • use Type to turn on a special layout and behaviour: If a supported value is assigned, the TextBox gets a 'Find' button to its left and a label to the right. The Find Button launches a find screen to look up valid values (or to look up Partners, in case of 'PartnerKey') and the label shows the description of the value (or the 'ShortName' of a Partner in case of 'PartnerKey'). Supported Values are: 'PartnerKey', 'Extract', 'Occupation'. More values can be added; contact us if you need more lookups and we can tell you how to add them.
• chk: CheckBox
  • use CheckBoxAttachedLabel to optionally have a Label directly attached to the CheckBox. This Label can be displayed left or right of the CheckBox Control. The value of 'CheckBoxAttachedLabel' can be 'right' or 'left', depending on which side of the CheckBox the Label should appear.
    • This is not to be confused with the Label that is automatically generated for e.g. TextBoxes and CheckBoxes which is placed in the preceding 'column' of the generated layout. The directly attached Label goes into the same 'colum' as the CheckBox!
  • A CheckBox can have a list of dependent other controls in an optional 'Controls' list. Those Controls get enabled when the tick mark is displayed in the CheckBox and disabled if the tick mark isn't displayed.
• nud: Numeric Up/Down
  • has a second label LabelUnit, which can be optionally set
  • use PositiveValueActivates to enable a condition when a positive value is selected
• rbt: simple RadioButton
  • see also: RadioButton group
• cmb: ComboBox (DropDown). A TextBox with a button that opens a list underneath from which values can be chosen. (Usually uses our custom control Ict.Common.Controls.TCmbAutoComplete.)
  • see also Overview Comboboxes
  • attribute OptionalValues defines the values of the combobox; prepend the default option with equals sign
    • sample: OptionalValues: [=Days, Weeks, Months]
  • attribute List: this will load the values from the server (and use a cache as well); it will use cmbAutoPopulatedComboBox instead of TCmbAutoComplete
    • possible values for list: eg. CurrencyCodeList
    • sample: cmbCurrency: {Label=&Currency, DataField=AApSupplier.CurrencyCode, List=CurrencyCodeList}
  • attribute AutoComplete: this will store the entered search strings in the user defaults
    • cmbSupplierCode: {Label=S&earch Supplier, AutoComplete=SupplierSearchHistory, Tooltip=Search by supplier name or partner key}
  • attribute: MultiColumn: this will generate a TCmbVersatile combobox with several columns; make sure to set the column width of the second or more columns, otherwise they will not be visible! (not used yet anywhere)

Other Controls

• lbl: Label. Displays text. Labels are automatically generated for TextBoxes, unless the value NoLabel is specified for a TextBox.
• btn: Button.
  • use Action to specify the Action that should be executed when the Button is clicked/pressed.

Advanced Controls

• grd: Grid control
  • use SelectedRowActivates to enable a condition when a row is selected
  • use event ActionFocusRow that is called when the selection of the current row changes
  • special control with name "grdDetails" is required for the Master/Detail screens
  • property SortOrder defines which column should be sorted. Several columns can be separated by commas; it is necessary to add DESC or ASC; example: SortOrder: ABatch.BatchNumber DESC
  • property Columns lists the columns to be displayed
  • property TableName makes the list in Columns shorter...
• trv: TreeView

Printing

• ppv: PrintPreview. This is currently only used internally, by the PrintPreviewWithToolbar
• pre: PrintPreview With Toolbar: this is used with the windowBrowsePrint template. a toolbar is added with current page, number of all pages, buttons for previous and next page, and print current page and general print button.

ToolBars

• tbb: ToolBar Button
• tbl: ToolBar Label
• ttx: ToolBar TextBox
• cmb: ToolBar ComboBox
  • Width specifies the width of the ComboBox in pixels.

Data Binding

We don't use .Net databinding, but the generator wires the data.

• You can use the attributes MasterTable and DetailTable that will try to match each control to the field in the table with the same name (detail fields must be called <prefix>Detail<fieldname>, eg. txtDetailAmount)
• You can specifically bind data with DataField, either with the data table name or just the field name.
  • sample: DataField=AApSupplier.CurrencyCode
• For some controls, eg radiobuttons used for filtering the displayed data, you need to avoid that the Save button gets activated: use SuppressChangeDetection: true

special lookups

• PartnerShortNameLookup: this is for printing the partner short name on a screen; usually this is read-only; but you need to specify that with ReadOnly=true
  • sample: txtSupplierName: {Label=Current Supplier, ReadOnly=true, PartnerShortNameLookup=AApDocument.PartnerKey}

special behaviour

• if you link a boolean database field to a combobox with 2 values, it will match the value (first value is false, second value is true).
  • sample:
    OptionalValues: [=Invoice, Credit Note]
DataField: CreditNoteFlag

Events

• attribute OnChange points to a function that is called if the value in the control changes
  • sample: dtpDateIssued: {Label=&Date Issued, OnChange=UpdateCreditTerms}
  • This applies the same to all kinds of Controls, although the Events of various Controls which denote a 'change' are indeed different. The Generator hooks up the following Events for you when the attribute OnChange is used:
    • For all Controls other than the ones listed below: the 'ValueChanged' Event is hooked up.
    • TextBox: the 'TextChanged' Event is hooked up.
    • ComboBox/DropDown: the 'SelectedValueChanged' Event is hooked up.
    • CheckBox and RadioButton: the 'CheckedChanged' Event is hooked up.
    • DateTimePicker: the 'DateChanged' is hooked up.
• attribute Action points to an action that is executed for Click etc
  • actually, there is now a convention, ie. the name of the control matches the name of the action, and the sample would not be even necessary
  • sample: mniNewSupplier: {Action=actNewSupplier}
• attribute ActionClick/ActionDoubleClick points to a function that is called if the control is clicked
  • sample: grdSupplierResult: {Dock=Fill, ActionDoubleClick=actSupplierTransactions, SelectedRowActivates=cndSelectedSupplier}
• attribute ActionOpenScreen will open a screen (defined with full namespace); if PropertyForSubScreens is set for the form, and the new screen has that propery too, it will be assigned
  • sample: mniAccountsPayable: {Label=&Accounts Payable, ActionOpenScreen=Ict.Petra.Client.MFinance.Gui.AccountsPayable.TFrmAPMain}
• in a grid: attribute SelectedRowActivates: activate a condition/action, which other actions can depend on
• in a grid: ActionFocusRow is called when the selection of the current row changes