Engineering / Computers / Part 5 of 9
PropertyManager Pages
A PropertyManager page is the difference between a tool a colleague has to be taught and one they simply use. It appears where every other SOLIDWORKS command appears, behaves the way they already expect, and gives you something no ordinary window can: a selection box wired directly into the modelling session.
- Part 5 · Interface
- Handler contract
- Selection boxes
- Event lifecycle
KL-ENG-COMP-1505 · KEVOS® Knowledge Library · Australian English
Everything else in this series runs and finishes. A PropertyManager page does not: it opens, waits, and responds. That single change — from a sequence to an event-driven object — is the whole conceptual step, and it is why the code looks so different from anything in Parts 1 to 4.
01Why not simply use an ordinary window
A standard application window will work, and for a stand-alone batch tool it is often the right answer. Inside a modelling session it is the wrong one, for four reasons.
Selection boxes
The decisive advantage. A selection box lets the user pick geometry in the graphics area and hands your code the entities, already marked and typed. No ordinary window can do this.
Familiar behaviour
The page docks where every command docks. The tick and cross behave as they do everywhere else. Users do not have to learn anything.
Focus and modality
A separate window competes with the modelling session for focus and gets lost behind it. A page is part of the session.
Appearance follows the host
Scaling, theming and font changes are handled by SOLIDWORKS. Your page keeps looking correct across machines and releases without effort.
You get the native controls SOLIDWORKS provides and no others, laid out in the order you add them. There is no visual designer and no free-form layout. For the settings-and-selection interfaces most engineering tools need, that constraint is a benefit — it removes a week of layout work and produces something consistent.
02The three objects
A page always involves three things, and separating them clearly in your own mind removes most of the confusion in the published examples.
The page
Created by asking the application for one. Owns the title bar, the buttons at the
top, the message area and the controls. You hold it to show, update and close the
page.The handler
A class you write that implements the published handler interface. SOLIDWORKS calls
its methods when the user does anything — presses a button, ticks a box, selects
geometry, closes the page.The controls
Groups, labels, text boxes, number boxes, check boxes, option buttons, combo boxes,
list boxes, selection boxes, buttons and more. Each is created by the page or by a group
and returned to you as an object you keep for later.Every control is created with an integer identifier that you choose, and every event arrives carrying that identifier — not the control object. Your handler decides what happened by comparing identifiers. Define them as named constants in one place. Scattering literal numbers through a page is the most reliable way to produce a tool where the wrong button appears to have been pressed.
03Implementing the handler
The handler is a class that implements the published PropertyManager page handler interface. That interface is large — on the order of thirty-seven callbacks — and you must supply every one, even those you have no use for.
using SolidWorks.Interop.sldworks;
using SolidWorks.Interop.swconst;
using SolidWorks.Interop.swpublished;
public class MateHelperPage : IPropertyManagerPage2Handler9
{
// ---- control identifiers, defined once -------------------------
const int ID_GROUP = 100;
const int ID_SELECTION = 101;
const int ID_CLEARANCE = 102;
private ISldWorks swApp;
private IPropertyManagerPage2 page;
public MateHelperPage(ISldWorks app) { swApp = app; }
// ---- callbacks that matter to this page ------------------------
public void OnClose(int reason) { /* commit or discard */ }
public void AfterClose() { /* release references */ }
// ---- the remainder must exist, and may do nothing --------------
public void AfterActivation() { }
public void OnButtonPress(int id) { }
public void OnCheckboxCheck(int id, bool isChecked) { }
// ... and so on for every member of the interface
}Most callbacks will be empty in any given page, and that is expected. Development environments will generate the full set of stubs for you; accept them, then fill in only the handful you care about. A page that responds to a selection and a close is a complete and useful page.
The handler interface carries a version number that has incremented across releases as callbacks were added. Implement the highest-numbered variant your target release exposes and record which one, because moving to an older release means implementing a different interface rather than adjusting an argument.
04Creating and showing the page
The page itself is created by the application, given a title, a set of options and your handler. It reports failure through an output argument rather than by returning nothing, so read it.
int errors = 0;
int options = (int)(swPropertyManagerPageOptions_e.swPropertyManagerOptions_OkayButton
| swPropertyManagerPageOptions_e.swPropertyManagerOptions_CancelButton
| swPropertyManagerPageOptions_e.swPropertyManagerOptions_LockedPage);
page = (IPropertyManagerPage2)swApp.CreatePropertyManagerPage(
"Mate Helper", options, this, ref errors);
if (page == null) { /* report and stop */ return; }
page.SetMessage3("Select two faces to mate.",
(int)swPropertyManagerPageMessageVisibility.swImportantMessageBox,
(int)swPropertyManagerPageMessageExpanded.swMessageBoxMaintainExpandState,
"How to use this");
// ... add groups and controls here ...
page.Show2(0);| Option | Effect | When to use it |
|---|---|---|
| Okay button | Adds the confirm control at the top of the page | Almost always |
| Cancel button | Adds the cancel control | Almost always — users need a way out that commits nothing |
| Locked page | Prevents the page closing when the user selects geometry or switches document | Essential for any page that asks the user to select something |
| Pushpin button | Lets the user keep the page open after confirming | Tools applied repeatedly in one sitting |
| Preview button | Adds a preview control your code is responsible for handling | Where the result is worth showing before committing |
| Multiple pages | Shows previous and next navigation | Genuinely multi-step workflows only |
Without the locked-page option, the page closes the moment the user clicks in the graphics area — which is precisely what you have just asked them to do. This is the single most common reason a first PropertyManager page appears not to work.
05Groups and controls
Controls are added to a group, and groups to the page. Layout is determined entirely by the order in which you add them; the identifier plays no part in positioning.
int groupOptions = (int)(swAddGroupBoxOptions_e.swGroupBoxOptions_Expanded
| swAddGroupBoxOptions_e.swGroupBoxOptions_Visible);
var group = (IPropertyManagerPageGroup)page.AddGroupBox(
ID_GROUP, "Mate definition", groupOptions);
int controlOptions = (int)(swAddControlOptions_e.swControlOptions_Enabled
| swAddControlOptions_e.swControlOptions_Visible);
var selBox = (IPropertyManagerPageSelectionbox)group.AddControl2(
ID_SELECTION,
(short)swPropertyManagerPageControlType_e.swControlType_Selectionbox,
"Faces to mate",
(short)swPropertyManagerPageControlLeftAlign_e.swControlAlign_Indent,
controlOptions,
"Select the two faces to be made coincident");
selBox.SingleEntityOnly = false;
selBox.Height = 50;
selBox.SetSelectionFilters(new int[] { (int)swSelectType_e.swSelFACES });
selBox.Mark = 1;Setting a filter on a selection box means the user physically cannot put the wrong kind of entity into it. Setting a mark means your code can retrieve exactly that box's contents from the selection manager, regardless of what else is selected. Used together, they remove most of the validation code Part 4 needed — keep the validation anyway, but it will stop firing.
06The event lifecycle
Once the page is shown, control returns to SOLIDWORKS and your code runs only when called. Understanding the order of those calls is what makes a page behave predictably.
- After activationThe page is on screen. Set initial values here if they depend on the current document state.
- User interactionSelections, typing, ticking and button presses each raise their own callback, carrying the control identifier and the new value.
- Selection submittedA callback fires before an entity enters a selection box, and its return value can reject the selection. This is where a rule too specific for a filter belongs.
- CloseCalled with a reason — confirmed, cancelled, or closed for some other cause. All work that changes the model belongs here, gated on the reason.
- After closeThe page is gone. Release references and clear state. Do not attempt to read controls; they no longer exist.
Modifying the model as the user types or selects makes cancellation meaningless and produces a rebuild on every keystroke. Gather state in fields as events arrive, and apply it once in the close callback when the reason indicates confirmation. This one habit accounts for most of the difference between a page that feels solid and one that feels erratic.
07Design guidance
Say what you need first
Use the message area to state what the user should select or enter. It costs one call and removes most support questions.
Fewer controls, better defaults
Every control is a decision imposed on the user. Where a sensible default exists, apply it and move the control into a collapsed group.
Group by task, not by type
Groups should follow the order of the work, so the page reads as a procedure rather than as a settings list.
Validate as you go
Reject impossible input at the point of entry using ranges and the submit-selection callback, rather than presenting an error after the user has confirmed.
Show the count
Where a selection box needs a specific number of entities, update the message to show how many have been picked. Users should never have to guess whether the page agrees with them.
Leave nothing behind
Clear selections, restore filters and release references on close — on the cancelled path exactly as on the confirmed one.