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

Context Navigation

FORM_ADD_BUTTON

Adds a button item to a form.

void FORM_ADD_BUTTON(formName name, buttonName, int x, int y, const char* pszText, char cShortcut, EVENT_FNC event, uint32 nFlag, const char* pszHelp, int nIDVal = 0, int x2 = -1, int y2 = -1, const char* pszBitmap, PALETTE_ITEM* pTrans = NULL);

Parameters

formName - name of the form, this much match the name of the FORM_INIT
buttonName - name of the input, this must be unique within this form
x - X coordinate (0 - 639)
y - Y coordinate (0 - 479)
pszText - Text to display in button
cShortcut - Shortcut key to press to activate button
event - Event to be called when button is activated, may be NULL to not call event
nFlag - Flags such as FORM_UINT8_SEL to show selection data
pszHelp - Help text to be displayed at the bottom of screen when field is selected
nIDVal - optional ID that may be used for return value when button is pressed if event function is not used
x2 - optional X2 coordinate for right of button (0 - 639)
y2 - optional Y2 coordinate for bottom of button (0 - 479)
pszBitmap - optional bitmap filename for bitmap to display in button
pTrans - optional color to designate for bitmap to appear as transparent

Return Value

This function does not return any value

Remarks

FORM_ADD_BUTTON is a macro to simplify the creation of buttons on forms. The preprocessor will replace this with two lines of code: The creation of the CFormButton with the specified name and then the call to the Add function of the specified form to add the button.

#define FORM_ADD_BUTTON(f, name, x, y, label, shortcut, func, nFlag, moreargs...) \
				CFormButton btn##name((x),(y),(label),(shortcut),(func),(nFlag), ##moreargs); \
				form##f.Add(btn##name)

The FORM_ADD_BUTTON macro should not be inserted in a condition. An entire form FORM_INIT .. FORM_HIDE may be in a condition. If any FORM_ADD_BUTTON macros are in conditions the form will then have an invalid pointer for each occurrence. The reason is that the FORM_ADD_BUTTON macro declares a CFormButton item and then adds the item to the specified form. The CFormButton 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.

Button Styles

FORM_BUTTON
FORM_BUTTON_BIG
FORM_BUTTON_OUTLINE
FORM_BUTTON_INVERT
FORM_BUTTON_OWNERDRAW

FORM_BUTTON_INVERT is recommended for new apps. This can be combined with FORM_OUTLINE_xLINE_WND (x = number of lines of extra text inside the button: can be from 1 to 15) flag and FORM_SHOW_EVENT flag to create buttons that show settings within the button.

Examples

void MenuScreen(void)
{
    FORM_INIT(Menu, EventMenuShow, NULL, NULL, NULL, nFormFlgShowHelp);
    FORM_ADD_BUTTON(Menu, SetDateTime, 0, 50, "1. Set Date/Time", '1', EventDateTime, FORM_BUTTON);
    FORM_ADD_BUTTON(Menu, ViewAccum, 0, 80, "2. View Accumulators", '2', EventViewAccum, FORM_BUTTON);

    FORM_SHOW(Menu);
    FORM_RUN(Menu);
    FORM_HIDE(Menu);
}

EVENT(MenuShow)
{
    ClearLCD();
    DisplayText(0, 0, "Menu Screen");
    return 0;
}

EVENT(SetDateTime)
{
    // Hide the parent form
    IN_EVENT_HIDE_FORM;

    DateTimeScreen();

    // Show the parent form
    IN_EVENT_SHOW_FORM;

    return 0;
}

EVENT(ViewAccum)
{
    // Hide the parent form
    IN_EVENT_HIDE_FORM;

    ViewAccumScreen();

    // Show the parent form
    IN_EVENT_SHOW_FORM;

    return 0;
}

This example is a program fragment showing how to use bitmaps in buttons.

const int ZERO_BTN_X = (FONT_WIDTH * 10);
const int ZERO_BTN_Y = (FONT_HEIGHT * 19);
const int ZERO_BTN_X2 = ZERO_BTN_X + FONT_WIDTH * 9;
const int ZERO_BTN_Y2 = ZERO_BTN_Y + FONT_HEIGHT * 3;
const char* const BMP_FILE_ZERO = "/usr/images/zero.bmp";

PALETTE_ITEM trans;
trans.red = 128;
trans.green = 192;
trans.blue = 192;
trans.alpha = 0;

FORM_ADD_BUTTON(Main, Zero, ZERO_BTN_X, ZERO_BTN_Y, "Zero", 'Z', EventZero, FORM_BUTTON_INVERT, NULL, 0, ZERO_BTN_X2, ZERO_BTN_Y2, BMP_FILE_ZERO, &trans);