Contents Up Previous Next

wxForm: wxObject

The purpose of the form class
Constraints on form items
Form appearance
Example
wxForm::wxForm
wxForm::~wxForm
wxForm::Add
wxForm::AssociatePanel
wxForm::Delete
wxForm::FindItem
wxForm::IsEditable
wxForm::OnCancel
wxForm::OnHelp
wxForm::OnOk
wxForm::OnRevert
wxForm::OnUpdate
wxForm::RevertValues
wxForm::Set
wxForm::SetEditable
wxForm::UpdateValues
Functions for making form items and constraints


The purpose of the form class

The wxForm provides form-like functionality, relieving the programmer of the tedium of defining all the physical panel items and the callbacks handling out-of-range data. It allows the application writer to write form dialogs quickly (albeit programmatically) with panel items being chosen automatically according to the given constraints. The supplied form demo shows how succinct a form definition can be. A form gets laid out from left to right; the programmer can intersperse new lines and specify item sizes, but for brevity no more control is allowed.

A form does not presuppose a particular type of panel: any window derived from wxPanel may be associated with a form, once the form has been built by adding form items. Also, a form reads from and writes to any C++ variables in your program---just supply pointers to the variables, and the form handles the rest.


Constraints on form items

Each item in a form may be supplied with zero or more constraints, where the range of possible constraints depends on the data type, and the displayed panel item depends upon the data type and the constraint(s) given. For example, a string form item with a list of possible strings as a constraint will produce a list box on the panel; an integer form item with a range constraint will result in a slider being displayed. The user may define his or her own constraint by passing a function as a constraint which returns FALSE if the constraint was violated, TRUE otherwise. The function should write an appropriate message into the buffer passed to it if the constraint was violated.


Form appearance

Once displayed on a panel, a form shows Ok, Cancel, Update, Revert and Help buttons along the top, with the user-supplied items below. When the user presses Ok, the form items are checked for violation of constraints; if any violations are found, an appropriate error message is displayed and the user must correct the mistake (or press Cancel, which leaves the item values as they were after the last Update). Pressing Update also checks the constraints and updates the values, but typically does not dismiss the dialog. Revert causes the displayed values to take on the values at the last Update. Pressing Help cause the OnHelp member to be called, which by default does nothing. By default, the OnOk and OnCancel messages dismiss and delete the dialog box and form, but these may be overridden by the application (see below).

The display-type values which may be passed to a form-item creation function are as follows:

wxFORM_DEFAULT Let wxWindows choose a suitable panel item.
wxFORM_SINGLE_LIST Use a single-selection listbox. Default for string item with a one-of constraint.
wxFORM_CHOICE Use a choice item.
wxFORM_CHECKBOX Use a checkbox. Default for boolean item.
wxFORM_TEXT Use a single-line text item. Default for floating point item, and for string and integer items with no constraints.
wxFORM_MULTITEXT Use a multi-line text item.
wxFORM_RADIOBOX Use a radiobox with a one-of constraint.
wxFORM_SLIDER Use a slider. Default for integer item with range constraint.

The wxFormItem and wxFormItemConstraint classes are not detailed in this manual since their members do not need to be directly accessed by the user. Functions for creating form items and constraints for passing to wxForm::Add are given in the next subsection.


Example

The following is an example of a form definition, taken from the form demo. Here, a new form MyForm has been derived, and a new member EditForm has been defined to edit objects of the type MyObject, given a panel to display it on.

void MyForm::EditForm(MyObject *object, wxPanel *panel)
{
  Add(wxMakeFormString("string 1", &(object->string1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintFunction(MyConstraint), 0)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormString("string 2", &(object->string2), wxFORM_DEFAULT,
                  new wxList(wxMakeConstraintStrings("One", "Two", "Three", 0), 0)));
  Add(wxMakeFormString("string 3", &(object->string3), wxFORM_CHOICE,
                       new wxList(wxMakeConstraintStrings("Pig", "Cow",
                                  "Aardvark", "Gorilla", 0), 0)));
  Add(wxMakeFormNewLine());
  Add(wxMakeFormShort("int 1", &(object->int1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintRange(0.0, 50.0), 0)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormFloat("float 1", &(object->float1), wxFORM_DEFAULT,
                       new wxList(wxMakeConstraintRange(-100.0, 100.0), 0)));
  Add(wxMakeFormBool("bool 1", &(object->bool1)));
  Add(wxMakeFormNewLine());

  Add(wxMakeFormButton("Test button", (wxFunction)MyButtonProc));

  AssociatePanel(panel);
}

wxForm::wxForm

void wxForm(int useButtons = wxFORM_BUTTON_ALL,
int placeButtons = wxFORM_BUTTON_AT_TOP)

Constructor. The value of useButtons determines which buttons are automatically created, and must be a bit list of the following identifiers:

wxFORM_BUTTON_ALL is the same as specifying all buttons except wxFORM_BUTTON_HELP.

placeButtons may be used to specify whether the form buttons are placed the top or bottom of the form, and may be one of:


wxForm::~wxForm

void ~wxForm(void)

Destructor. Does not delete the associated panel or any panel items, but does delete all form items.


wxForm::Add

void Add(wxFormItem *item, long id = -1)

Adds a form item to the form. If an id is given this is associated with the form item; otherwise a new id is generated, by which the item may be identified later.


wxForm::AssociatePanel

void AssociatePanel(wxPanel *panel)

Associates the form with the given panel (or window derived from wxPanel, such as wxDialogBox). This causes a number of items to be created on the panel using information from the list of form items. The panel should be shown after this has been called.


wxForm::Delete

Bool Delete(long id)

Deletes the given form item by id. Returns TRUE if successful.


wxForm::FindItem

wxNode * FindItem(long id)

Given a form item id, returns a list node containing the form item.


wxForm::IsEditable

Bool IsEditable(void)

Returns TRUE if the form can be edited.


wxForm::OnCancel

void OnCancel(void)

This member may be derived by the application. When the user presses the Cancel button, this is called, allowing the application to take action. By default, OnCancel deletes the form and the panel associated with it, probably the normal desired behaviour.


wxForm::OnHelp

void OnHelp(void)

This member may be derived by the application. When the user presses the Help button, this is called, allowing the application to take action.


wxForm::OnOk

void OnOk(void)

This member may be derived by the application. When the user presses the OK button, this is called, allowing the application to take action. By default, OnOk deletes the form and the panel associated with it, probably the normal desired behaviour. Note that if any form item constraints were violated when the user pressed OK, the member does not get called.


wxForm::OnRevert

void OnRevert(void)

This member may be derived by the application. When the user presses the Revert button, the C++ form item variable values in effect before the last Update are restored. Then this member is called, allowing the application to take further action.


wxForm::OnUpdate

void OnUpdate(void)

This member may be derived by the application. When the user presses the Update button, the C++ form item variable values are updated to the values on the panel. Then this member is called, allowing the application to take further action.


wxForm::RevertValues

void RevertValues(void)

Internal function for displaying the C++ form item values in the displayed panel items. Should not need to be called by the user.


wxForm::Set

Bool Set(long id, wxFormItem *item)

Given a form item id, replaces an existing item with that id with the given form item. Returns TRUE if successful.


wxForm::SetEditable

void SetEditable(Bool id)

Sets the form to be editable (TRUE) or read-only (FALSE).


wxForm::UpdateValues

Bool UpdateValues(void)

Internal function for setting the C++ form item values to the values set in the panel items. Should not need to be called by the user.


Functions for making form items and constraints

These functions make form items and their associated constraints for passing to wxForm::Add.

wxFormItem * wxMakeFormButton(char *label, wxFunction fun)

Makes a button with a conventional callback.

wxFormItem * wxMakeFormMessage(char *label)

Makes a message.

wxFormItem * wxMakeFormNewLine(void)

Adds a newline.

wxFormItem * wxMakeFormLong(char *label, long *var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = 0, int width = -1,
int height = -1)

Makes a long integer form item, given a label, a pointer to the variable holding the value, an item type, and a list of constraints (see below). style may be wxHORIZONTAL or wxVERTICAL (for label orientation). help_string is currently not used.

wxFormItem * wxMakeFormShort(char *label, int *var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = 0, int width = -1,
int height = -1)

Makes an integer form item, given a label, a pointer to the variable holding the value, an item type, and a list of constraints (see below). style may be wxHORIZONTAL or wxVERTICAL (for label orientation). help_string is currently not used.

wxFormItem * wxMakeFormDouble(char *label, double *var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = 0, int width = -1,
int height = -1)

wxFormItem * wxMakeFormFloat(char *label, float *var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = 0, int width = -1,
int height = -1)

Makes a floating-point form item, given a label, a pointer to the variable holding the value, an item type, and a list of constraints (see below). style may be wxHORIZONTAL or wxVERTICAL (for label orientation). help_string is currently not used.

wxFormItem * wxMakeFormBool(char *label, Bool *var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = 0, int width = -1,
int height = -1)

Makes a boolean form item, given a label, a pointer to the variable holding the value, an item type, and a list of constraints (see below). style may be wxHORIZONTAL or wxVERTICAL (for label orientation). help_string is currently not used.

wxFormItem * wxMakeFormString(char *label, char **var,
int item_type = wxFORM_DEFAULT, wxList *constraints = NULL,
char *help_string = NULL, int style = NULL, int width = -1,
int height = -1)

Makes a string form item, given a label, a pointer to the variable holding the value, an item type, and a list of constraints (see below). style may be wxHORIZONTAL or wxVERTICAL (for label orientation). help_string is currently not used.

wxFormItemConstraint * wxMakeConstraintStrings(wxList *list)

Makes a constraint specifying that the value must be one of the strings given in the list.

wxFormItemConstraint * wxMakeConstraintStrings(char *first, ...)

Makes a constraint specifying that the value must be one of the strings given in the variable-length argument list, terminated with a zero.

wxFormItemConstraint * wxMakeConstraintFunction(wxConstraintFunction func)

Makes a constraint with a function that gets called when the value is being checked. The function should return FALSE if the constraint was violated, TRUE otherwise. The function should also write an appropriate message into the buffer passed to it if the constraint was violated. The type wxConstraintFunction is defined as follows:

typedef Bool (*wxConstraintFunction)(int type, char *value, char *label, char *msg)

type is the type of the item, for instance wxFORM_STRING. value is the address of the variable containing the value, and should be coerced to the correct type, except for wxFORM_STRING, where no coercion is required.

wxFormItemConstraint * wxMakeConstraintRange(double lo, double hi)

Makes a range constraint; can be used for integer and floating point form items.