company logo

ControlContext :: associateData - Associate data/instance from base collection

The function associates one or more instances from the base collection of the current control to the collection, the current control is based on. Typically, the source collection is the base collection defined for the control or database property.

The function opens a standard dialogue, which lists the instances of the source collection and a check box for selecting instances to be linked. One may define an own selection list layout by defining a control with the name associate in the class the base collection refers to. The default control name (associate) can be overwritten when calling the function.

After selecting one or more items, selected items are, usually, added to the data source (which is a data source for the control) by calling action InsertEntry. Before calling InsertEntry, string data is stored to the control's text area and the doBeforeStoreData() handler is called. Thus, each associated entry may be handled by the doBeforeStoreData() handler rather than by the default associate handling. in order to suppress InsertEntry action, the handler should return true (error) in order to suppress InsertEntry action.
Return value:  State of function return ( bool  )

A State true indicates, that the function was executed successfully. Otherwise state is false.

Implementation overview

Implementation details

  1. Create associate dialog with user-defined list control
    bool ControlContext  :: associateData ( odaba::String &sControl, odaba::String &sTitle )

    The function calls the associate dialog and displays the title passed in sTitle in the title bar of the dialog.

    The name of the control to be displayed in the associate dialog is passed in sControl. When passing an empty control name, "associate" is assumed as control name. The control name is looked for in the class defined by the base collection. When no control with the passed name could be found, a default list control is created internally.

    The items displayed in the list are the elements in the base collection defined for the field in the designer. When no base collection has been defined in the designer, the default base collection defined for the property in the data model will be displayed as base collection.

    • sControl - Control name

      The control name is the name of the control resource as being defined within the parent control.

      "city"         // search city control in current control

      "..city"       // search city control in parent-parent-control

      "address.city" // search city control in subordinated address form
    • sTitle - Title for window or control
    2. to list
  2. Create associate dialog with application data source
    bool ControlContext  :: associateData ( odaba::Property &cSourceProperty, odaba::String &sControl, odaba::String &sTitle )

    The function calls the associate dialog and displays the title passed in sTitle in the title bar of the dialog.

    The name of the control to be displayed in the associate dialog has to be passed in sControl. When passing an empty control name, "associate" is assumed as control name. The control name is looked for in the class defined by the base collection. When no control with the passed name could be found, a default list control is created internally.

    The items displayed in the list are the instances from the property handle passed in rSourceProperty. Since selected items will be linked to the control data source later on, the data type in the property handle passed to the function must be compatible with the data type of the control data (property()).
    • cSourceProperty - Source property handle

      The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.

    • sControl - Control name

      The control name is the name of the control resource as being defined within the parent control.

      "city"         // search city control in current control

      "..city"       // search city control in parent-parent-control

      "address.city" // search city control in subordinated address form
    • sTitle - Title for window or control
    3. to list
  3. Create associate dialog with default data source
    bool ControlContext  :: associateData ( odaba::String &sTitle )

    The function calls the associate dialog and displays the title passed in sTitle in the title bar of the dialog.

    The control used for displaying associate candidates is theassociate control defined in the class of the base collection or, when no associate control is defined in the class, an internally defined check list.

    The items displayed in the list are the elements in the base collection defined for the field in the designer. When no base collection has been defined in the designer, the default base collection defined for the property in the data model will be displayed as base collection.

    • sTitle - Title for window or control
    4. to list
to top next upper table of contents Comment