wiki:Docs/Prog/Manual/ApplicationLibraries/lib825ev/Form/FORM_ADD_INPUT

Context Navigation

FORM_ADD_INPUT

Adds an input item to a form.

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, string& strVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, float& fVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, uint8& byVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, uint16& nVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, uint32& nVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

void FORM_ADD_INPUT(formName name, inputName, int x, int y, const char* pszPrompt, int nLen, int nMin, int nMax, event, void* pVal, uint32 nFlag, const char* pszChoices, const char* pszHelp, int nIDVal = 0);

Parameters

formName - name of the form, this much match the name of the FORM_INIT
inputName - name of the input, this must be unique within this form
x - X coordinate (0 - 639)
y - Y coordinate (0 - 479)
pszPrompt - Prompt text
nLen - Maximum input length
nMin - For numeric input minimum accepted value
nMax - For numeric input maximum accepted value
event - Event to be called when field is updated, may be NULL to not call event.
strVal - String field data, when form starts will display contents of the string, when form is completed new data will be written to string
fVal - Floating point number field data, when form starts display the value, when form is completed new data will be written to string
nFlag - Flags such as FORM_UINT8_SEL to show selection data
pszChoices - Character array of choices such as "COM1|COM2|COM3" for flag FORM_UINT8_SEL
pszHelp - Help text to be displayed at the bottom of screen when field is selected
nIDVal - Custom ID value that may be used in some cases

Return Value

This function does not return any value

Remarks

FORM_ADD_INPUT is a macro to simplify the creation of inputs on forms. The preprocessor will replace this with two lines of code: The creation of the CFormInput with the specified name and then the call to the Add function of the specified form to add the input.

#define FORM_ADD_INPUT(f, name, x, y, prompt, len, min, max, func, pval, flag, choices, help, moreargs...) \
				CFormInput inp##name((x),(y),(prompt),(len),(min),(max),(func),(pval),(flag),(choices),(help), ##moreargs); \
				form##f.Add(inp##name)

The FORM_ADD_INPUT macro should not be inserted in a condition. An entire form FORM_INIT .. FORM_HIDE may be in a condition. If any FORM_ADD_INPUT macros are in conditions the form will then have an invalid pointer for each occurrence. The reason is that the FORM_ADD_INPUT macro declares a CFormInput item and then adds the item to the specified form. The CFormInput item will go out of scope at the end of the condition. If conditional items are needed the FORM_FLAG_DISABLE may be used to make the item hidden. The CForm::EnableItem function may then be used to conditionally show the item.

Examples

void IDScreen(void)
{
    string strID = "";
    float fVal = 0.0;
    uint8 bySel = 0;

    FORM_INIT(ID, EventIDShow, NULL, NULL, NULL, nFormFlgShowHelp);
    FORM_ADD_INPUT(ID, ID, 0, 50, "ID: ", 10, 0, 0, NULL, strID, 0, NULL, "Enter the ID");
    FORM_ADD_INPUT(ID, Val, 0, 80, "Value: ", 10, 0, 9999, NULL, fVal, 0, NULL, "Enter the value");
    FORM_ADD_INPUT(ID, Sel, 0, 110, "Select: ", 10, 0, 2, NULL, bySel, FORM_UINT8_SEL, "Truck|Pickup|Car", "Press SPACE to select type");

    FORM_SHOW(ID);
    FORM_RUN(ID);
    FORM_HIDE(ID);

    // strID, fVal, and bySel now contain the entered data
}

EVENT(IDShow)
{
    ClearLCD();
    DisplayText(0, 0, "ID/Value Screen");
    return 0;
}