Purpose

Adds a new button object to the manager

Protoype

void CButtonMngr::AddButton (string str_id, string str_tilemap, int i_rows, int i_cols, int i_xpos, int i_ypos, 
                             int i_button_up, int i_button_down, int i_button_over, int i_button_disabled, 
                             int i_button_stick, int i_state, string str_icon, string str_caption, bool b_icon_visible, 
                             bool b_cap_visible, bool b_visible, string str_cursor = "", string str_sfx_up = "", 
                             string str_sfx_down = "", string str_sfx_over = "", string str_sfx_disabled = "")

Parameters

Description

This function creates a new button object. Each button object must have a unique ID so that it can be later referenced in the application. The ID of the new button is passed in for str_id. The location on the screen you would like this button to appear is passed in via i_xpos and i_ypos.

Button Templates

A button template is the image object that is used to create the button. A button template must be made up of four cells, however the cells can be arranged in any order and in any size and shape. This is an example of a button template.

Althought the template above is arranged on a single row, it could also be in a square formation or in a single column. In order for the renderer to compensate for this, you must pass in the proper values for the number of rows into i_rows and the number of columns in to i_cols. In this case the values would equate to 1 row, 4 columns.

Button States

A button can have four states, as evident above. In the example, the first cell is the up-state, the second is the over-state, the third is the down-state and the fourth is the disabled-state. These states can be ordered in any which way. In order for the renderer to be able to extract the correct cell matching the current button state, you must pass in the correct cell numbers for the state parameters i_button_up, i_button_down, i_button_over, and i_button_disabled. You must also pass in a cell number for i_button_stick, which is the cell you want the button to revert to when "stuck". A "stuck" button remains in that state until clicked on again (like a check box). Finally, you must set the initial state of the button itself by passing in one of the cell numbers for i_state.

NOTE: Cells begin with 0, not 1!

Captions and Icons

If you want, the button can contain a caption and/or icon to display. The caption is a CText text object, and the icon is a CImage image object. You must pass in their IDs for str_caption and str_icon respectively. When you do this the image and/or text gets bound to the button, and wherever the button goes so will the contents. Text and/or icons will also be automatically centered on the button. Why have both at once? You could have a button with an icon and then on a mouse-over change the icon to a caption. If you do not want a caption and/or icon, pass in NO_BCONTENT.

Button and Content Visibility

You have the option of hiding the button, which will also hide the caption and/or icon, or just the icon and/or caption. b_icon_visible controls the visibility of the button's icon. Pass in TRUE to display the icon and FALSE to hide it. b_cap_visible controls the visibility of the button's caption. Pass in TRUE to display the caption and FALSE to hide it. b_visible controls the visibility of the button itself. Pass in TRUE to display it and FALSE to hide it.

NOTE: Don't forget that hiding a button will also automatically hide its contents, although when reshowing a button, you do not also have to manually reshow any contents that were hidden with the button.

NOTE: You can display icons and captions at the same time.

Button Cursors

If you want the mouse cursor to automatically change when it hovers over a button, then you would pass in for str_cursor the ID of the CCursor object you want the cursor to turn into when a mouse-over event occurs for this button. When the cursor moves off the button it will be restored to its previous state. If you don't want a button cursor then use NO_BCONTENT.

Button Sounds

You can set sounds to be played for the various button events by passing in CSound SFX IDs for the four states - str_sfx_up, str_sfx_over, str_sfx_down, and str_sfx_disabled. If you don't want a sound for a particular event, use NO_BSFX.

Use

CButtonMngr button;

// this button is using the example template above
button.AddButton("my_button", "button_template", 1, 4, 200, 200, 0, 1, 2, 3, 3, 0, "my_icon", NO_BCONTENT, true, false, 
                 true, NO_BCONTENT, NO_BSFX, "click");