CoreSuite.TextBoxActionPanel 1.0.0

TextBoxActionPanel

A non-visual Windows Forms component that adds a configurable image-action panel to an existing TextBoxBase control.

TextBoxActionPanel enhances a text box already placed on a form. It does not create a replacement text box and does not require the target control to inherit from a new CoreSuite class.

The component is displayed in the Visual Studio component tray, like ToolTip, ErrorProvider, and ContextMenuStrip. At run time, it shows a compact row of image buttons above or below the associated text box while that field has focus.

Highlights

• Attaches to any existing control derived from TextBoxBase.
• Works with standard TextBox and RichTextBox controls.
• Works with CoreSuite controls derived from TextBoxBase, including QueriedBox.
• Appears in the Windows Forms component tray instead of occupying the form surface.
• Provides a designer-serializable Actions collection.
• Displays the first action at the right edge and adds subsequent actions toward the left.
• Uses NoFocusCueButton internally for action buttons.
• Shows and hides automatically as the target receives and loses focus.
• Uses a non-activating popup, allowing the target text box to keep keyboard focus during button clicks.
• Automatically follows target movement, resizing, parent movement, scrolling, and form movement.
• Supports automatic, above-only, and below-only placement.
• Supports a general ActionClicked event and an optional delegate for each action.
• Supports run-time changes to images, tooltips, visibility, enabled state, ordering, sizing, spacing, and colors.
• Provides XML documentation and Visual Studio property descriptions for the public API.

Requirements

• .NET 8 for Windows (net8.0-windows)
• Windows Forms
• CoreSuite.NoFocusCueButton

The NuGet dependency on CoreSuite.NoFocusCueButton is resolved automatically when the package is installed.

Installation

Install the package with the .NET CLI:

dotnet add package CoreSuite.TextBoxActionPanel

Or search for CoreSuite.TextBoxActionPanel in the Visual Studio NuGet Package Manager.

Namespace

Imports CoreSuite.Controls

Designer setup

1. Place the desired TextBox, QueriedBox, or other TextBoxBase-derived control on the form.
2. Add TextBoxActionPanel from the Toolbox.
3. Select the component in the component tray.
4. Set TargetControl to the existing text box.
5. Open the Actions collection editor.
6. Add, remove, or reorder TextBoxAction items.
7. Configure Key, Image, ToolTipText, AccessibleName, Visible, and Enabled for each item.
8. Handle the component's ActionClicked event.

The component intentionally does not draw buttons over the text box in the Visual Studio Designer. The floating panel is created only at run time.

One component per target control is recommended because each component owns its own target, action collection, appearance, and events.

Basic event handling

Assume the form contains:

• a TextBox named CustomerTextBox;
• a TextBoxActionPanel named CustomerActions;
• actions with the keys View, Search, and Create.

Handle every action through the general event:

Private Sub CustomerActions_ActionClicked(Sender As Object, E As TextBoxActionClickEventArgs) Handles CustomerActions.ActionClicked
    Select Case E.Action.Key
        Case "View"
            ViewCustomer(E.TargetControl.Text)
        Case "Search"
            SearchCustomer(E.TargetControl.Text)
        Case "Create"
            CreateCustomer(E.TargetControl.Text)
    End Select
End Sub

E.TargetControl is the actual existing control assigned to TargetControl. It can be cast to its specific type when access to derived members is required:

Dim ProductBox As QueriedBox = DirectCast(E.TargetControl, QueriedBox)

Per-action delegate

Delegates are assigned at run time because the Windows Forms Designer cannot serialize function references:

Private Sub MainForm_Load(Sender As Object, E As EventArgs) Handles MyBase.Load
    Dim CreateAction As TextBoxAction = CustomerActions.Actions.FindByKey("Create")
    If CreateAction IsNot Nothing Then CreateAction.ClickHandler = AddressOf CreateCustomerAction
End Sub
Private Sub CreateCustomerAction(E As TextBoxActionClickEventArgs)
    MessageBox.Show($"Create a customer from: {E.TargetControl.Text}")
End Sub

When an action is executed, ActionClicked is raised first and the action's ClickHandler delegate is invoked afterward. Applications normally choose one mechanism for a given action to avoid handling the same command twice.

Creating actions in code

Dim ViewAction As TextBoxAction = CustomerActions.Actions.Add("View", My.Resources.View16, "View the selected customer.")
Dim SearchAction As TextBoxAction = CustomerActions.Actions.Add("Search", My.Resources.Search16, "Search for a customer.")
Dim CreateAction As TextBoxAction = CustomerActions.Actions.Add("Create", My.Resources.Create16, "Create a customer.")
CreateAction.ClickHandler = AddressOf CreateCustomerAction

A 16-by-16 pixel image is recommended. The default button is 24 by 24 pixels and centers the image without modifying it.

Action order

Collection order is interpreted from right to left:

Invisible actions do not reserve space. Reordering the collection immediately changes the visual order the next time the panel is rebuilt.

TextBoxAction properties

ClickHandler is hidden from the Property Grid and excluded from designer serialization.

Keys are not required to be unique, but unique keys are strongly recommended. FindByKey and PerformAction use the first case-insensitive match.

Component properties

Association and behavior

Layout

Values outside these ranges raise ArgumentOutOfRangeException.

Appearance

Methods

ShowPanel

Displays the panel when the target, owner form, component state, and visible actions permit it.

CustomerActions.ShowPanel()

HidePanel

Hides the panel without clearing the target or actions.

CustomerActions.HidePanel()

RefreshPanel

Rebuilds visible buttons and recalculates the position when the panel is open.

CustomerActions.RefreshPanel()

Changing an action or appearance property already requests this refresh automatically.

PerformAction

Executes an enabled action by key and returns whether execution occurred:

If Not CustomerActions.PerformAction("Search") Then
    MessageBox.Show("The Search action is unavailable.")
End If

Key comparison is case-insensitive. A hidden but enabled action can still be executed programmatically; Visible controls presentation, while Enabled controls execution.

Events

Focus behavior

The panel is hosted in a borderless window configured not to activate. Its internal buttons are also removed from keyboard selection and have TabStop = False.

Consequently:

• typing continues in the target text box while the panel is visible;
• clicking an action button does not focus that button;
• the target's caret and selection remain controlled by the target;
• normal focus changes still hide the panel when HideOnLeave is enabled;
• closing a modal dialog restores the panel when keyboard focus returns to the target;
• deactivating or closing the owner form hides the panel.

An action delegate can intentionally move focus or open another form. Such application behavior is not overridden by the component.

Placement behavior

Placement = Auto prefers the area above the target. When the panel would extend beyond the current screen's working area, it uses the area below the target. Forced Above or Below placement is clamped to the working area so the popup remains reachable.

The right edge of the panel is aligned with the right edge of the target whenever screen space permits.

Using more than one target

Use a separate component for each field:

CustomerActions -> CustomerTextBox
ProductActions  -> ProductQueriedBox
OrderActions    -> OrderRichTextBox

This keeps each field's actions, visibility rules, delegates, and event wiring independent.

Compatibility with QueriedBox

QueriedBox derives from TextBox, which derives from TextBoxBase, so it can be assigned directly:

ProductActions.TargetControl = ProductQueriedBox

The action component does not read or modify query configuration, frozen values, primary keys, text, or selection state. An event handler can access those members by casting E.TargetControl back to QueriedBox.

Image lifetime

The component references action images but does not clone or dispose them. Images stored in form resources remain owned by those resources. Images created dynamically should be disposed by the code that created them after the panel and its buttons are no longer using them.

Accessibility

Every button receives an accessible name using this priority:

1. AccessibleName
2. ToolTipText
3. Key

Because the floating buttons intentionally do not participate in keyboard focus traversal, applications should provide an equivalent keyboard command when the action is essential. PerformAction can be used from a shortcut handler.

Package information

License

This package is distributed under the MIT license used by the CoreSuite repository.