Library

Form

Form

Settings Every Control Takes

Every control is built from its GPAL factory, GPAL.Button, GPAL.Input, GPAL.ListView and so on, and every one of them takes the settings on this page. WithName gives the control the name a workflow and UIAutomation find it by. WithText sets the text it displays. WithWidth and WithHeight set its size in pixels, and a control given a width keeps that width and sits centered rather than stretching across the form. WithToolTip sets the hover text and WithToolTipDelay how long that text stays on screen, five seconds without one and never less than one. WithShortcutKey binds a Keys combination that acts on the control. WithTag holds any object alongside the control for the workflow's own use, and GPAL never reads it. ToGPALObject ends the chain and hands back the control to pass to WithFormControl. Text controls also take WithFont, WithTextAlignment for where the text sits inside the control, and WithAutoSize to let the control size itself to its text. WithEnabled(false) greys a control out, and the Enabled property reads and writes the same state while the form is up, from any thread. WithReadOnly shows a value without letting it be edited, on the controls that hold one. WithPlaceholder sets the grey prompt shown while a field is empty. WithChecked presets a checkbox or radio button, and Default on a button makes it the one Enter presses. Callbacks are the same everywhere. WithCallback takes the handler and ForEvent names which event it answers, one of Click, DoubleClick, TextChanged, SelectedIndexChanged, CheckedChanged, ValueChanged, AfterSelect, KeyDown, Scroll, ItemChecked, CellValueChanged, SplitterMoved, DragDrop, DragEnter, DragLeave or DragOver. Without ForEvent the handler is wired to whatever that control treats as its primary event: Click for a button, a label, a picture and a chart, CheckedChanged for a checkbox and a radio button, TextChanged for an input, a text area, a rich text box and a file selector, ValueChanged for a slider, a numeric up-down and a date picker, SelectedIndexChanged for a combo box, a list view and a tab, CellValueChanged for a data grid, and AfterSelect for a tree view. A splitter answers SplitterMoved, which is where the user dragged the divider to, and that is its default. A group box and a table layout panel hold controls rather than being interacted with, so a handler belongs on what is inside them. A menu bar and a toolbar are the same: each GPALBarItem carries its own callback, defaulting to Click. WithCallbackOffUIThread runs the handler on a worker thread instead, so the form keeps painting while it works, and GPAL controls the handler sets marshal themselves. It takes any of the handler types below except the two the event reads an answer from as the handler returns, a drag handler setting args.Effect and a key handler setting args.Handled. Those stay on the UI thread and GPAL publishes a WARNING saying so. The type argument to WithCallback is the delegate the event carries. Most of them carry EventHandler, which is why nearly every sample in these pages says WithCallback<EventHandler>. Eight events carry one of six other types: KeyDown takes KeyEventHandler, DragDrop, DragEnter and DragOver take DragEventHandler, CellValueChanged on a data grid takes DataGridViewCellEventHandler, ItemChecked on a list view takes ItemCheckedEventHandler, AfterSelect on a tree view takes TreeViewEventHandler, and SplitterMoved takes SplitterEventHandler. DragLeave is the odd one in that group and takes plain EventHandler, because it carries no drag data. Two names are portable across controls but do not carry the same delegate on each one. Scroll is ScrollEventHandler on a tab and EventHandler on a slider. Change is a convenience that resolves to whatever the control calls changing, so it is DataGridViewCellEventHandler on a data grid, TreeViewEventHandler on a tree view, and EventHandler everywhere else it is offered. Default has the same shape: it attaches to the control's primary event, so its delegate is whatever that event carries. A file selector is the one control whose handler is given something other than the event's own arguments. Its Default, Change and Click callbacks are EventHandler, but what arrives is a FileSelectorEventArgs, delivered when the dialog closes rather than when the path box changes. Cast the args to read Cancelled, SelectedPath and SelectedPaths, which is how a workflow tells a cancelled dialog from a chosen file. TextChanged is the exception and behaves normally, since that is the path box's own event.

NOTE

WithName narrows the chain to the settings every control shares, so anything specific to that control has to come before it. WithEnabled, WithReadOnly, WithChecked, WithPlaceholder, WithItems, WithColumns and Default all belong ahead of WithName. This is the single ordering rule the form API has.

WARNING

WithCallback takes the handler as a type argument and GPAL casts it to what the event expects when the form is built. A handler of the wrong type is not a compile error; it throws at that moment. If a form fails as it is being shown and the message names a cast, this is why: check the delegate against the event, not the control.

Examples

GPAL Fluent: High-level fluent C# API

//Each control is declared as its own field so a handler can reach it by name. The cast is to the control type, GPALButton, GPALInput, GPALLabel, which is the same thing ToGPALObject hands back. WithCallback is a list rather than a single slot, so a control can carry as many handlers as it needs and ForEvent applies to the WithCallback immediately before it. A WithCallback with no ForEvent after it goes to the control's primary event, which is Click on a button and TextChanged on an input. Keep each pair together in the chain and the reading order is the declaration order. The handler's own signature comes from the delegate, which is the practical reason the type argument matters: EmailKeyDown takes KeyEventArgs and can therefore read KeyCode, which an EventHandler never could.

// the same settings, on three different controls

GPALButton save = (GPALButton)GPAL.Button

.WithText("Save")

.WithWidth(120)

.WithToolTip("Write the rows to disk")

.WithShortcutKey(Keys.Alt | Keys.S)

.WithCallback<EventHandler>(SaveClicked)

.WithName("save");


// two handlers on one control. ForEvent names the event for the WithCallback right before it,

// so each pair is read together and the order in the chain is the order they are declared

GPALInput email = (GPALInput)GPAL.Input

.WithPlaceholder("you@example.com")

.WithEnabled(false)

.WithCallback<EventHandler>(EmailChanged).ForEvent(ControlEventType.TextChanged)

.WithCallback<KeyEventHandler>(EmailKeyDown).ForEvent(ControlEventType.KeyDown)

.WithName("email");


GPALLabel heading = (GPALLabel)GPAL.Label

.WithText("Customer")

.WithFont(new Font("Georgia", 14))

.WithTextAlignment(ContentAlignment.MiddleCenter)

.WithName("heading");


// every setting is a property as well, so the workflow or another control's handler can change it

// after the form is built

email.Enabled = true;


// the handlers. the signature is the delegate's, so KeyDown gets KeyEventArgs and can read the key

void SaveClicked(object sender, EventArgs args)

{

// whatever saving means for this form

}


void EmailChanged(object sender, EventArgs args)

{

save.Enabled = false == string.IsNullOrWhiteSpace(email.Text);

}


void EmailKeyDown(object sender, KeyEventArgs args)

{

// Enter in the box does what Save does, and args.Handled keeps the key from going further

if (Keys.Enter == args.KeyCode)

{

args.Handled = true;

SaveClicked(sender, args);

}

}

On this page

Form
Settings Every Control Takes
  • Examples
    • 💬 Ask GPAL