SalQuickTabs

Namespace: PPJ.Runtime.Windows.QO

Assembly: PPJ.Web.50 (5.0.0.0)

Hosts tab pages, associated sibling controls, and lazily created form pages.

C#

public class SalQuickTabs : SalUserControl, IExtenderProvider

VB.NET

Public Class SalQuickTabs
    Inherits SalUserControl
    Implements IExtenderProvider

Example:

using PPJ.Runtime.Windows.QO;

var tabs = new SalQuickTabs();
tabs.TabSetup = "{Name=general;Label=General;Form=}";

Constructors

SalQuickTabs()

Initializes the tab frame, page setup, and selection event handlers.

Properties

Alignment

TabAlignment: Gets or sets the edge along which tab headers are arranged.

AllowUserToMoveTabs

Boolean: Gets or sets whether users can drag tabs to reorder them. (Default: False)

ImageList

ImageList: Gets or sets the image list used by tab headers. (Default: null)

ItemSize

Size: Gets or sets the configured tab-header size in pixels.

Orientation

Orientation: Gets or sets the orientation of the tab headers.

PageRectangle

Rectangle: Gets the page display rectangle in pixels relative to the frame's parent.

SelectedIndex

Int32: Gets or sets the selected page index. (Default: 0)

During selection processing, the getter can expose the requested index. A nonnegative assignment also stores the initial selection; out-of-range assignments do not select a page.

SelectedTab

TabPage: Gets or sets the selected page in the inner tab control.

ShowVisibilityMenu

Boolean: Gets or sets whether the tab-visibility menu is shown. (Default: False)

SizeMode

TabSizeMode: Gets or sets how the inner tab control sizes its headers.

TabControl

TabControl: Gets the inner platform tab control.

TabPages

SalTabPageCollection: Gets the collection that manages this frame's pages.

TabSetup

String: Gets or sets the initial page definitions and reloads changed definitions. (Default: "")

Each definition uses the format {Name=Name0;Label=Label0;Form=FormClass0}.

Methods

Add(bRedraw)

Appends an unnamed tab page.

Parameter	Type	Description
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalNumber. The zero-based index of the new page.

AddPage(sTag, sForm, hWnd)

Registers a tab-name to form-class binding without creating the form.

Parameter	Type	Description
sTag	SalString	The internal tab name identifying a form binding.
sForm	SalString	The form class name used for later page creation.
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. False if the name is already bound; otherwise, true.

Example:

Create a named tab and register the form class that will supply its page content.

using PPJ.Runtime;
using PPJ.Runtime.Windows;
using Wisej.Web;
using PPJ.Runtime.Windows.QO;

public class CustomerPage : SalFormWindow
{
    public CustomerPage()
    {
        Text = "Customer details";
    }
}

public static class TabExample
{
    public static bool AddCustomers(SalQuickTabs tabs)
    {
        // Use an empty tab control so index zero is the first page.
        if (!tabs.AddPage(0, "customers"))
            return false;
        tabs.SetLabel(0, "Customers", true);
        // Registration does not create CustomerPage immediately.
        return tabs.AddPage("customers",
            (SalString)typeof(CustomerPage).FullName, SalWindowHandle.Null);
    }
}

AddPage(pageIndex, pageName)

Inserts a page and assigns its internal name.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
pageName	SalString	The internal page name.

Returns: SalBoolean. True if inserted; false for an invalid insertion index.

Example:

Insert the first page and set its display label independently of its internal name.

using PPJ.Runtime;
using PPJ.Runtime.Windows;
using Wisej.Web;
using PPJ.Runtime.Windows.QO;

public static class TabExample
{
    public static bool AddCustomers(SalQuickTabs tabs)
    {
        // Use an empty tab control so index zero is the first page.
        if (!tabs.AddPage(0, "customers"))
            return false;
        tabs.SetLabel(0, "Customers", true);
        return true;
    }
}

AddPageEx(pageIndex, pageName, imageFile, tooltip)

Inserts a named page with an optional image file and tooltip.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
pageName	SalString	The internal page name.
imageFile	SalString	The optional image-file path.
tooltip	SalString	The tab-header tooltip text.

Returns: SalBoolean. True after insertion; false for an invalid insertion index.

Image-loading errors propagate after the page is inserted.

ApplyFormPageChanges()

Sends the apply notification to every instantiated bound form page.

Returns: SalBoolean. True.

AssociateChild(pageIndex, child)

Adds a page name to a child control's tab associations.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
child	Control	The child control to associate or disassociate.

Returns: SalBoolean. True if associated or already associated; false for a null child or invalid page.

AttachWindow(pageIndex, form)

Binds an existing control to a tab and shows it when that tab is active.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
form	Control	The existing control to bind as page content.

Returns: SalBoolean. True if bound; false for an invalid page, null control, or existing binding.

BringToTop(nIndex, bRedraw)

Requests selection of a tab page.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalBoolean. True for a valid page index; false for an invalid index.

CancelMode()

Marks the current user-request processing as canceled.

Returns: SalBoolean. True.

Call while handling a tab-change request.

Clear(bRedraw)

Removes all tab pages.

Parameter	Type	Description
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalBoolean. True.

ClearPages()

Closes or disposes all instantiated bound form pages and removes their bindings.

Returns: SalBoolean. True.

CreatePage(sTag)

Creates the form bound to a named tab if it has not already been created.

Parameter	Type	Description
sTag	SalString	The internal tab name identifying a form binding.

Returns: SalBoolean. False for a missing tab or empty form class; true after processing or if the page already exists.

Design mode creates a placeholder label. Runtime creation sends the page-initialization notification when a control is available.

Delete(nIndex, bRedraw)

Removes a page at the supplied index.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

The redraw flag controls immediate refresh.

DestroyPage(sTag)

Removes a form-page binding and closes or disposes its instantiated control.

Parameter	Type	Description
sTag	SalString	The internal tab name identifying a form binding.

Returns: SalBoolean. True if the binding existed; otherwise, false.

DetachWindow(pageIndex)

Removes a tab's form binding without disposing the bound control.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalWindowHandle. The detached control handle, or a null handle for an invalid page or missing binding.

DisablePage(pageIndex)

Disables a tab page.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

DisassociateChild(pageIndex, child)

Removes a page name from a child control's associations.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
child	Control	The child control to associate or disassociate.

Returns: SalBoolean. True if processed or already unassociated; false for a null child or invalid page.

Enable(nIndex, bEnable)

Sets whether a tab page is enabled.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
bEnable	SalBoolean	True to enable the page; false to disable it.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

Disabled pages are excluded from normal user selection.

EnablePage(pageIndex)

Enables a tab page.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

FindLabel(sLabel)

Finds the first page whose Text exactly matches the supplied caption.

Parameter	Type	Description
sLabel	SalString	The page caption.

Returns: SalNumber. The zero-based index, or -1 if absent.

FindName(sName)

Finds the first page whose internal name exactly matches.

Parameter	Type	Description
sName	SalString	The page name.

Returns: SalNumber. The zero-based index, or -1 if absent.

FindTabFrame(hWndForm)

Finds the first QuickTabs frame within a form's child traversal.

Parameter	Type	Description
hWndForm	SalWindowHandle	The form in which to search for a tab frame.

Returns: SalWindowHandle. The frame handle, or a null handle if no frame or form is found.

FromHandle(hWnd)

Resolves a SAL handle to an existing QuickTabs frame.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalQuickTabs. The frame, or null if no control is found.

An incompatible control causes InvalidCastException.

GetActivePage()

Reads the active page index.

Returns: SalNumber. The GetTop result.

GetClicked()

Reads the index recorded for the current tab-click notification.

Returns: SalNumber. The clicked-tab index reported by the inner control.

Call during a click notification.

GetContentsBorderRect(nLeft, nTop, nRight, nBottom)

Reads border offsets in form units from the frame's docking padding.

Parameter	Type	Description
nLeft	SalNumber	The left bound or margin in form units; receives the value for getter methods.
nTop	SalNumber	The top bound or margin in form units; receives the value for getter methods.
nRight	SalNumber	The right bound or margin in form units; receives the value for getter methods.
nBottom	SalNumber	The bottom bound or margin in form units; receives the value for getter methods.

Returns: SalBoolean. True.

GetContentsRect(nLeft, nTop, nRight, nBottom)

Reads the page display rectangle in form units relative to the frame's parent.

Parameter	Type	Description
nLeft	SalNumber	The left bound or margin in form units; receives the value for getter methods.
nTop	SalNumber	The top bound or margin in form units; receives the value for getter methods.
nRight	SalNumber	The right bound or margin in form units; receives the value for getter methods.
nBottom	SalNumber	The bottom bound or margin in form units; receives the value for getter methods.

Returns: SalBoolean. True.

GetContentsRectPixels(nLeftPixels, nTopPixels, nRightPixels, nBottomPixels)

Reads the page display rectangle in pixels relative to the frame's parent.

Parameter	Type	Description
nLeftPixels	SalNumber	Receives the left edge in pixels.
nTopPixels	SalNumber	Receives the top edge in pixels.
nRightPixels	SalNumber	Receives the right edge in pixels.
nBottomPixels	SalNumber	Receives the bottom edge in pixels.

Returns: SalBoolean. True.

GetControlTabPages(control)

Reads the tab-name association of a child control.

Parameter	Type	Description
control	Control	The child control whose tab association is read or changed.

Returns: String. The semicolon-separated names, or an empty string if unassociated.

GetCount()

Counts the frame's tab pages.

Returns: SalNumber. The page count.

GetLabel(nIndex, sLabel)

Reads the page caption into the output string.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
sLabel	SalString	Receives the caption for a valid index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

The output is unchanged for an invalid index.

GetMarginRect(nLeft, nTop, nRight, nBottom)

Reads the docking-padding margins in form units.

Parameter	Type	Description
nLeft	SalNumber	The left bound or margin in form units; receives the value for getter methods.
nTop	SalNumber	The top bound or margin in form units; receives the value for getter methods.
nRight	SalNumber	The right bound or margin in form units; receives the value for getter methods.
nBottom	SalNumber	The bottom bound or margin in form units; receives the value for getter methods.

Returns: SalBoolean. True.

GetName(nIndex, sName)

Reads a page's internal name into the output string.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
sName	SalString	Receives the page name for a valid index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

The output is unchanged for an invalid index.

GetPageIndex(pageName)

Finds a page by its internal name.

Parameter	Type	Description
pageName	SalString	The internal page name.

Returns: SalNumber. The page index, or -1 if absent.

GetPageName(pageIndex)

Reads a page's internal name.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalString. The name, or SalString.Null for an invalid page.

GetPageTitle(pageIndex)

Reads a page caption.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalString. The caption, or SalString.Null for an invalid page.

GetPageWindow(sTag)

Gets the existing control bound to a tab name.

Parameter	Type	Description
sTag	SalString	The internal tab name identifying a form binding.

Returns: SalWindowHandle. The control handle, or a null handle if no binding or control exists.

GetPageWindow(pageIndex)

Gets a tab's bound control or the tab-page handle when no binding exists.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalWindowHandle. The control/page handle, or a null handle for an invalid index or uninstantiated binding.

GetRowCount()

Accepts the tab-header row-count compatibility query.

Returns: SalNumber. One.

The Web implementation logs that the query is unsupported.

GetTooltip(pageIndex, tooltip, maxLength)

Copies a page tooltip truncated to the requested character count.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
tooltip	SalString	Receives the truncated tooltip for a valid index.
maxLength	SalNumber	The maximum tooltip character count.

Returns: SalNumber. The copied character count, or zero for an invalid page.

An invalid page leaves the output unchanged.

GetTop()

Reads the selected tab index.

Returns: SalNumber. The selected index, or -1 when no page is selected.

HidePage(pageIndex)

Hides a tab page.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

HideWindow(hWnd)

Hides a control and keeps it hidden across tab changes.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if the control is found; otherwise, false.

HideWindowAndLabel(hWnd)

Hides a control and its label across tab changes.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if the control is found; otherwise, false.

IndexFromPoint(nX, nY)

Finds the header containing a point in this frame's client coordinates.

Parameter	Type	Description
nX	SalNumber	The horizontal client coordinate in pixels.
nY	SalNumber	The vertical client coordinate in pixels.

Returns: SalNumber. The header index, or -1 if no header contains the point.

InitializeFormPages()

Sends the initialization notification to every instantiated bound form page.

Returns: SalBoolean. True.

Insert(nIndex, bRedraw)

Inserts an unnamed page while preserving the selected numeric index.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalBoolean. True if inserted; false if the index is outside zero through the page count.

IsAssociatedWithTab(nIndex, hWnd)

Tests whether a control is associated with a tab page.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if associated; false for an invalid page, unresolved control, or missing association.

IsEnabled(nIndex)

Tests whether a valid tab page is enabled.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for an enabled page; false for an invalid or disabled page.

IsWindowVisible(hWnd)

Tests whether a control is present in the frame's explicitly hidden set.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if explicitly hidden; false if absent from the set or unresolved.

Despite the method name, true indicates that HideWindow registered the control as hidden.

Next()

Requests selection of the next valid tab.

Returns: SalNumber. The next-valid-tab index returned by the inner control.

OnLoad(e)

Completes tab initialization before raising the base Load event.

Parameter	Type	Description
e	EventArgs	The event data.

At runtime prepares page layout and moves the frame behind sibling content.

OnResize(e)

Raises the base resize event and updates form-page sizing.

Parameter	Type	Description
e	EventArgs	The event data.

When ready, invokes the parent tab sizing callbacks; otherwise resizes pages directly.

PageCount()

Counts the tab pages.

Returns: SalNumber. The page count.

Prev()

Requests selection of the preceding valid tab.

Returns: SalNumber. The previous-valid-tab index returned by the inner control.

Redraw()

Updates the inner tab control's display.

Returns: SalBoolean. True.

ReloadTabs()

Reloads the stored TabSetup definitions and refreshes the frame.

Returns: SalBoolean. True.

RemovePage(pageIndex)

Deletes a page and requests refresh.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

RenamePage(pageIndex, pageName)

Changes a page's internal name and also its caption when the old caption equals the old name.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
pageName	SalString	The internal page name.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

ResizePages()

Applies the supplied or stored bounds to instantiated form pages.

Returns: SalBoolean. True.

ResizePages(rect)

Applies the supplied or stored bounds to instantiated form pages.

Parameter	Type	Description
rect	Rectangle	The page bounds in pixels relative to their parent.

Returns: SalBoolean. True.

SendMsgToAssociated(nIndex, nMsg, wParam, lParam)

Sends a message to controls associated with a tab and their children in tab order.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
nMsg	SalNumber	The message identifier.
wParam	SalNumber	The message's first numeric parameter.
lParam	SalNumber	The message's second numeric parameter.

Returns: SalBoolean. False for a negative index; true after processing, including when no controls match.

The index must fit the association arrays.

SetActivePage(pageIndex)

Requests activation of a page through BringToTop.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. The BringToTop result.

SetControlTabPages(control, tabNames)

Associates a child control with named tabs and updates its visibility.

Parameter	Type	Description
control	Control	The child control whose tab association is read or changed.
tabNames	String	Semicolon-separated tab names, or null/empty to remove the association.

Null or empty names remove the association. The tab frame cannot be associated with itself.

SetCurrentPage(sTag)

Creates and shows the named bound form page, hiding the previous page.

Parameter	Type	Description
sTag	SalString	The internal tab name identifying a form binding.

Returns: SalBoolean. True.

The new page receives activation before the old page receives deactivation. An absent binding clears the current-page reference.

SetImage(nIndex, tResource)

Assigns a non-null image or image resource to a tab header.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
tResource	SalResource	The tab image resource.

Returns: SalBoolean. True if assigned; false for an invalid index, null image, or unsupported resource.

The image list entry is keyed by the page name. Null inputs leave the existing image unchanged.

SetImage(nIndex, image)

Assigns a non-null image or image resource to a tab header.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
image	Image	The tab image.

Returns: SalBoolean. True if assigned; false for an invalid index, null image, or unsupported resource.

The image list entry is keyed by the page name. Null inputs leave the existing image unchanged.

SetLabel(nIndex, sLabel, bRedraw)

Changes the tab caption and processes embedded image-resource notation.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
sLabel	SalString	The page caption.
bRedraw	SalBoolean	Whether to request immediate redraw; ignored where the platform operation always updates.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

A resolved resource is assigned to the tab image.

SetName(nIndex, sName)

Changes a page's internal name and updates its form binding and active-page display.

Parameter	Type	Description
nIndex	SalNumber	The zero-based page index.
sName	SalString	The page name.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

An existing form binding matching the new name is retained.

SetPageSize(nLeft, nTop, nRight, nBottom, bResize)

Stores the bounds used for bound form pages and optionally resizes them immediately.

Parameter	Type	Description
nLeft	SalNumber	The left bound or margin in form units; receives the value for getter methods.
nTop	SalNumber	The top bound or margin in form units; receives the value for getter methods.
nRight	SalNumber	The right bound or margin in form units; receives the value for getter methods.
nBottom	SalNumber	The bottom bound or margin in form units; receives the value for getter methods.
bResize	SalBoolean	Whether to apply the bounds to existing pages immediately.

Returns: SalBoolean. True.

SetPageSize(rect, bResize)

Stores the bounds used for bound form pages and optionally resizes them immediately.

Parameter	Type	Description
rect	Rectangle	The page bounds in pixels relative to their parent.
bResize	SalBoolean	Whether to apply the bounds to existing pages immediately.

Returns: SalBoolean. True.

SetPageTitle(pageIndex, pageTitle)

Changes a page caption without changing its internal name.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
pageTitle	SalString	The caption displayed on the tab.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

SetTooltip(pageIndex, tooltip)

Sets the tooltip displayed over a tab header.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.
tooltip	SalString	The tab-header tooltip text.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

This does not change tooltip text on its content window.

SetWorkspaceBoundary(nMinWidth, nMinHeight)

Sets the minimum frame size from dimensions expressed in form units.

Parameter	Type	Description
nMinWidth	SalNumber	The minimum width in horizontal form units.
nMinHeight	SalNumber	The minimum height in vertical form units.

Returns: SalBoolean. True.

ShowPage(pageIndex)

Makes a tab page visible.

Parameter	Type	Description
pageIndex	SalNumber	The zero-based page index.

Returns: SalBoolean. True for a valid page index after applying the change; otherwise, false.

ShowSiblings()

Updates associated child-control visibility for the selected tab.

Returns: SalBoolean. The result of updating sibling visibility.

ShowWindow(hWnd)

Removes a control from the explicit hidden set and applies its current-tab visibility.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if the handle resolves to a control; otherwise, false.

ShowWindowAndLabel(hWnd)

Removes a control and its label from the hidden set and reapplies tab visibility.

Parameter	Type	Description
hWnd	SalWindowHandle	The target control handle.

Returns: SalBoolean. True if the control is found; otherwise, false.

Update()

Refreshes the tab display through Redraw.

Returns: SalBoolean. True.

Events

SelectedIndexChanged

EventHandler Occurs after the selected tab changes.

SelectedIndexChanging

TabCancelEventHandler Occurs before tab selection changes and allows cancellation.

Implements

Name	Description
ISalWindow	Provides SAL window actions, named properties, and access to a window's runtime implementation.