Userbar Function

It is possible to add a bar at the top of a data entry application to facilitate certain kinds of communication between a user and the intentions of the application programmer. For instance, a button can be added that allows the user to jump to a certain section of a questionnaire, or the bar can display reference text useful for the user. This "userbar" can display text, buttons, and text fields.

General Userbar Commands

b = userbar(show | hide | clear);

Show adds a userbar to the application, or if one has been added and is hidden, the show command displays it again. The hide command removes the userbar from the data entry window but keeps the userbar's contents in case it is shown again later. The clear command removes the userbar from the data entry window and deletes the contents of the userbar. The function returns 1 if successful, 0 otherwise. If the first command to a userbar is an add command, the userbar will be automatically displayed. If you want to add items to the userbar without displaying it, call hide or clear before adding the items.

Adding Items to the Userbar

i = userbar(add text | button | field | spacing,[...]);

All of the add commands, detailed below, return a resource identifier, an integer that uniquely points to the added object. If you plan to modify or remove objects added to the userbar, it is necessary to maintain this resource identifier as a way to identify on what object the modify or remove command should work. Objects are added to the userbar in left-to-right format. There is no way to add an item in between two existing items.

Adding Text to the Userbar

i = userbar(add text,alpha-expression);

The alpha-expression is a string of text that will be displayed on the userbar. The color of the text can be modified using the set color command.

Adding Buttons to the Userbar

i = userbar(add button,alpha-expression[,function-name]);

The button text comes from the alpha-expression. An optional argument specifies a function that is to be called when the button is pressed. If the function has parameters, it is necessary to specify the values of the arguments. The values of these arguments are evaluated when the button is activated by a user, not at the point that the button is added to the userbar. Several existing functions (mimicking options available on the CSEntry menu) can be specified using the do command:

i = userbar(add button,alpha-expression,do(alpha-expression));

The alpha-expression within the do command can be one of the following values:

"NextField", "PreviousField", "AdvanceToEnd", "EditNote", "ChangeLanguage", "PartialSave", "FieldHelp", "InsertLevelOcc", "AddLevelOcc", "DeleteLevelOcc", "InsertGroupOcc", "InsertGroupOccAfter", "DeleteGroupOcc", "SortGroupOcc", "PreviousScreen", "NextScreen", "EndGroupOcc", "EndGroup", "EndLevelOcc", "EndLevel", "FullScreen", "ToggleResponses", or "ToggleAllResponses"

Adding Fields to the Userbar

i = userbar(add field,alpha-expression[,function-name]);

The field's initial text comes from the alpha-expression. As with adding buttons, an optional argument specifies a function that is called when the user presses enter while typing text in the field. The width of the field depends on the initial text, so if you want a large field that starts with a blank value, use a long but blank string to initialize the field. Modifying the text of the field will not affect its size.

Adding Spacing to the Userbar

i = userbar(add spacing,numeric-expression);

If you want to space out the items on the userbar, specify in numeric-expression the number of pixels to leave blank between the last-to-be and next-to-be added items.

Modifying Items on the Userbar

b = userbar(modify,resource-identifier,alpha-expression); // for text, buttons, and fields
b = userbar(modify,resource-identifier,function-name); // for buttons and fields
b = userbar(modify,resource-identifier,alpha-expression,function-name); // for buttons and fields
b = userbar(modify,resource-identifier,numeric-expression); // for spacing

To modify an item on the userbar, use the resource identifier that the function returned when the item was added to the userbar and specify the changes to the item. For buttons and fields, the text of the item and/or the function can be modified. The function returns 1 if successful, 0 otherwise.

Removing Items from the Userbar

b = userbar(remove,resource-identifier);

The remove command takes the item pointed to by the resource identifier off the userbar. The function returns 1 if successful, 0 otherwise.

Changing the Color of Items

b = userbar(set color[,resource-identifier],red-value,green-value,blue-value);

The background color of the userbar is changed by specifying the RGB (0 to 255) values of the desired color. Alternatively, if a resource identifier of a text item is passed, the color of the text item is changed. The function returns 1 if successful, 0 otherwise.

Identifying the Source of an Action

i = userbar(get);

The get command returns the resource identifier of the last clicked button or the last userbar field in which data was entered. If no event has occurred, the function returns 0.

Obtaining the Contents of a Field

b = userbar(get,resource-identifier,alpha-variable);

In this format, the get command returns the contents of a userbar field identified by the resource identifier. Alpha-variable must be an alphanumeric variable declared in the PROC GLOBAL section of the code. The function returns 1 if successful, 0 otherwise.

Userbar on Windows

Newline characters added as part of text, button text, or field text, are converted to space characters.

Userbar on Mobile Devices

The userbar shows up as an icon to the left of the field note icon. Only buttons are displayed on the userbar so any color changes or additions of fields or spacing will be ignored. Options that mimic the CSEntry menu, added via the do(...) command, will also be ignored.

Example

PROC GLOBAL

numeric ADD_OP = 1, SUBTRACT_OP = 2, MULT_OP = 3, DIVIDE_OP = 4, MOD_OP = 5, EXP_OP = 6;

numeric leftOperatorRID,rightOperatorRID,resultsRID;

alpha (30) leftOperator,rightOperator;
alpha (1) operatorTypeString;

function performMathOperation(numeric operationType)

    userbar(get,leftOperatorRID,leftOperator);
    userbar(get,rightOperatorRID,rightOperator);

    numeric leftNumber = tonumber(leftOperator);
    numeric rightNumber = tonumber(rightOperator);

    if countnonspecial(leftNumber,rightNumber) <> 2 or leftOperator = "" or rightOperator = "" then
        userbar(modify,resultsRID,"The supplied values are invalid!");
        userbar(set color,255,0,0);
    
    elseif rightNumber = 0 and operationType in DIVIDE_OP,MOD_OP then
        userbar(modify,resultsRID,"0 cannot be a denominator in a divide or modulo expression!");
        userbar(set color,255,0,0); 
    
    else
        numeric result;
        
        if      operationType = ADD_OP      then result = leftNumber + rightNumber; operatorTypeString = '+';
        elseif  operationType = SUBTRACT_OP then result = leftNumber - rightNumber; operatorTypeString = '-';
        elseif  operationType = MULT_OP     then result = leftNumber * rightNumber; operatorTypeString = '*';
        elseif  operationType = DIVIDE_OP   then result = leftNumber / rightNumber; operatorTypeString = '/';
        elseif  operationType = MOD_OP      then result = leftNumber % rightNumber; operatorTypeString = '%';
        elseif  operationType = EXP_OP      then result = leftNumber ^ rightNumber; operatorTypeString = '^';
        endif;
        
        userbar(modify,resultsRID,maketext("%0.2f %s %0.2f = %0.2f",leftNumber,operatorTypeString,rightNumber,result));
        userbar(set color,0,255,0);     
    
    endif;

end;


PROC USERBAR_FF

preproc

    userbar(clear);
    userbar(add text,"Enter two values and select an operation:");
    leftOperatorRID = userbar(add field,"               ");
    rightOperatorRID = userbar(add field,"               ");
    userbar(add button,"Addition",performMathOperation(ADD_OP));
    userbar(add button,"Subtraction",performMathOperation(SUBTRACT_OP));
    userbar(add button,"Multiplication",performMathOperation(MULT_OP));
    userbar(add button,"Division",performMathOperation(DIVIDE_OP));
    userbar(add button,"Modulo",performMathOperation(MOD_OP));
    userbar(add button,"Exponentiation",performMathOperation(EXP_OP));
    userbar(add spacing,50);
    resultsRID = userbar(add text," ");
    userbar(show);