Property Manager Pages and the Control Model

01Executive summary

02The handler class

Pages are driven by a class that implements the page handler interface. Implementing it generates a long list of members — these are the callbacks SolidWorks invokes as the user interacts with the page. Most will remain empty; the ones you fill are the page's behaviour.

1. StructureImplement the handler interface

   Generate every member of the interface. Clear the auto-generated bodies, return a benign value from any member that returns one, and leave the rest empty until needed.

2. StructureCreate the page in the constructor

   The constructor takes the application object and creates the page, so that constructing an instance and having a page are the same event.

3. StructureAdd controls in a dedicated method

   Called immediately after successful creation. Keeping it separate makes the layout readable and lets you rebuild controls without recreating the page.

4. StructureExpose an explicit show method

   Creation and display are separate concerns. A page can exist without being visible, which is what multi-page add-ins rely on.

5. StructureRelease in the after-close callback

   Null the page handle and every control handle when the page closes, not when the add-in unloads.

03Creating the page

object CreatePropertyManagerPage(
    string Title,
    int    Options,
    object Handler,
    ref int Errors
)

public bool Ok { get; private set; }

private IPropertyManagerPage2 _page;
private ISldWorks _sw;
private int _errors;

public InfoPage(ISldWorks app)
{
    _sw = app;

    try
    {
        _page = (IPropertyManagerPage2)_sw.CreatePropertyManagerPage(
            "Model information",
            (int)(swPropertyManagerPageOptions_e
                    .swPropertyManagerOptions_OkayButton |
                  swPropertyManagerPageOptions_e
                    .swPropertyManagerOptions_LockedPage),
            this,
            ref _errors);

        // A returned object does not mean success.
        if (_errors != (int)swPropertyManagerPageStatus_e
                            .swPropertyManagerPage_Okay)
        {
            Report("Page could not be created: " +
                   ((swPropertyManagerPageStatus_e)_errors));
            Ok = false;
            return;
        }

        AddControls();
        Ok = true;
    }
    catch (Exception ex)
    {
        Report("Page could not be created: " + ex.Message);
        Ok = false;
    }
}

04The control catalogue

Controls are added to the page after it exists. Every control needs a caption, an alignment, an options mask and a tooltip; because most controls share the same alignment and options, those are normally computed once and reused.

object AddControl(
    short  ID,
    short  ControlType,
    string Caption,
    short  LeftAlign,
    int    Options,
    string Tip
)

private const short IdFileName   = 1;
private const short IdRefresh    = 2;
private const short IdSheetList  = 3;

private IPropertyManagerPageLabel    _lblFileName;
private IPropertyManagerPageButton   _btnRefresh;
private IPropertyManagerPageCombobox _cboSheets;

private void AddControls()
{
    _page.SetMessage3(
        "Information about the active document.",
        (int)swPropertyManagerPageMessageVisibility
                .swImportantMessageBox,
        (int)swPropertyManagerPageMessageExpanded
                .swMessageBoxMaintainExpandState,
        "Model information");

    int opts = (int)(swAddControlOptions_e.swControlOptions_Enabled |
                     swAddControlOptions_e.swControlOptions_Visible);
    short align = (short)swPropertyManagerPageControlLeftAlign_e
                            .swControlAlign_LeftEdge;

    _lblFileName = (IPropertyManagerPageLabel)_page.AddControl(
        IdFileName,
        (short)swPropertyManagerPageControlType_e.swControlType_Label,
        "Document", align, opts, "Active document name");

    _btnRefresh = (IPropertyManagerPageButton)_page.AddControl(
        IdRefresh,
        (short)swPropertyManagerPageControlType_e.swControlType_Button,
        "Refresh", align, opts, "Re-read the active document");
}

05The identifier-driven callback model

Interaction does not arrive as a delegate attached to a control. It arrives as a call to a handler member, carrying the identifier you assigned. One method therefore serves every button on the page, and dispatch is your responsibility.

public void OnButtonPress(int Id)
{
    switch (Id)
    {
        case IdRefresh:
            RefreshFromActiveDocument();
            break;
    }
}

public void OnComboboxSelectionChanged(int Id, int Item)
{
    switch (Id)
    {
        case IdSheetList:
            ActivateSheet(Item);
            break;
    }
}

public void AfterClose()
{
    // Release page and control handles here, not at unload.
    _cboSheets = null;
    _btnRefresh = null;
    _lblFileName = null;
    _page = null;
}

06Showing, hiding and multi-page behaviour

Creation and display are deliberately separate. An add-in that presents a different layout for parts, assemblies and drawings creates the controls for all three, then shows and hides groups as the active document changes — which is far cheaper than tearing down and rebuilding the page on every switch.

1. Create once

   Build the page and every control group at construction, including the groups that are not initially relevant.

2. Toggle visibility

   On a document change, hide the groups that do not apply and show the one that does, then repopulate its values.

3. Show with the right mode

   The display call takes a mode argument. The stacked mode is what keeps a page open across the events that would otherwise dismiss it — essential for a page intended to persist while the user works.

4. Release on close

   Handle the after-close callback and null every handle. The page may be closed by the user at any time, independently of the add-in's lifetime.

07Quick reference

Handler

One class implementing the page handler interface; every member generated, most left empty.

Creation

Title, options mask, handler, and an error value passed by reference — check it.

Controls

Added after creation; each returns a typed handle you must store.

Identity

One constant identifier per control, matched to the field holding its handle.

Interaction

Callbacks carry the identifier; dispatch is yours to write.

Message area

Built into every page; reveal it rather than adding a label of your own.

Teardown

Null the page and all control handles in the after-close callback.

08Where this leads

Continue in this pathway

• Part 01Add-in architecture and the integration model
• Part 02Development environment and project configuration
• Part 03COM registration and add-in discovery
• Part 04Command Manager, menus and toolbars
• Part 05Property Manager Pages and the control model
• Part 06Event and notification architecture
• Part 07Add-in, stand-alone or hybrid
• Part 08Planning, structure and debugging discipline
• Part 09Deployment methods and installer engineering
• Part 10Licensing, distribution and commercialisation