Priorities on forms

Data aware controls may optionally be assigned a priority. Depending on the user's priority the control may be displayed as read-only or not displayed at all.

The priority is set against the FLD declaration within a DEFRECORD. Two priority values are specified, the update-priority and the display-priority. For the DEFRECORD itself, a category may be specified. The category is a numeric constant, which should be defined using DEFENUM:

DEF ENUM CategoryEnum
    DIM _Category_Sales=10
    DIM _Category_Marketing=20
END ENUM
DEFRECORD fred WITH CATEGORY _Category_Sales
    FLD a = "NUM(10,3)" WITH PRIORITY 8, 5
    FLD b = "NUM(10,3)" WITH PRIORITY 4, 2
    FLD c$10 WITH PRIORITY 6, 4
    FLD d = "NUM(2,1)" WITH PRIORITY N, 5
END RECORD

The form itself is not modified. When the form is displayed, for each category KCML will call an application specified function to determine the user-priority for this category. For each data-aware control the control will be read-only if the user-priority is less than the update-priority and not displayed at all if the user-priority is less than the display-priority. If a control is already read-only or hidden then this will not be overriden by the priority. A priority of N is higher than any user-priority.

The function to determin the user-priority for a category is set using KCML_Priority_SetCallback. For example:

PUBLIC CALLBACK 'GetCategoryPriority(Category)
    SELECT CASE (Category)
    CASE _Category_Sales
        RETURN 4
    CASE _Category_Marketing
        RETURN 6
    CASE ELSE
        RETURN 0
    END SELECT
END SUB
'KCML_Priority_SetCallback(SYM('GetCategory))

Using the example code above, a form with data aware controls a, b, c and d based on the flds above would appear as:

Control	update-priority	display-priority	display (user-priority is 4)
a	8	5	hidden
b	4	2	normal
c	6	4	read-only
d	N	5	hidden