As of Brass v0.21, all plugins can take advantage of the 100% Configuration System. This system allows for the plugin display panel to be designed visually by the plugin developer, then altered by any user of the plugin simply by pointing and clicking.

Brass provides this functionality through layout files. As the plugin developer you can use the SSEdit Panel Designer to create a default layout for your plugin's controls. The concept of this being a default layout is extremely important. Because the 100% Configuration System allows users of your plugin to completely redesign it's display, you are simply providing a default layout - how the plugin will look when it's first loaded.

The LOADLAYOUT statement instructs Brass to load the layout file and enable the 100% Configuration System. Under normal circumstances you should call LOADLAYOUT in your Init handler. You must not call LOADLAYOUT in any handler earlier than the Init handler (for example, RegRead). You must not call LOADLAYOUT in the Shutdown or ShutdownEnd handlers. Undefined behaviour may occur if you do so. You should not call LOADLAYOUT multiple times otherwise controls will be duplicated, however there is no technical reason to prevent you from doing so.

The normal process for using the 100% Configuration System in your plugin is as follows:

1. Create a new document in SSEdit by selecting "New" from the "File" menu
2. Open the Panel Designer by selecting "Panel Designer" from the "View" menu
3. Design your layout by drawing controls onto the canvas
4. Assign your controls a name by right clicking them and selecting "Properties". Refer to setcontrolname for details.
5. OK the Panel Designer
6. Use the Handler Wizardbar to add "Init" and "Shutdown" handlers
7. In your Init handler, add a call to LOADLAYOUT with no parameters as the first statement
8. In your Shutdown handler, add a call to savelayout as the last statement

LOADLAYOUT may be called with or without a filename as a parameter. Under normal circumstances you will only ever need to call LOADLAYOUT once in your Init handler, without any parameters. This instructs Brass to check the user's local system for any custom layouts for your plugin. If no custom layout is found, the default layout is loaded.

When you design your panel layout in the Panel Designer then distribute your plugin, your default layout is included as a file named "default_layout.sld" in the <Brass Install Folder>\SSE\<YourPluginName> folder. This is done automatically by SSEdit and the Pack Creator. When a user installs and runs your plugin for the first time, Brass loads the default_layout.sld when the LOADLAYOUT call is executed. Your layout and controls are then loaded into the plugin display panel. The user is then able to enter Design Mode and redesign your plugin's layout to their preference. When the user unloads your plugin, Brass writes the redesigned layout to "<CurrentUsername>_layout.sld" when the savelayout call is executed. In future, whenever the user loads your plugin, the custom layout in "<CurrentUsername>_layout.sld" will be used. This ensures that the user always sees their own custom layout, but can revert to your plugin's default layout at any time.

It is also possible to call LOADLAYOUT with a layout filename as a parameter. This is provided for future compatibility. Brass will load the specified layout file and insert the layout into the display panel. Because the layout is inserted (rather than used to overwrite the existing layout) this feature must be used with care. Brass always saves the layout of all controls in the panel when the savelayout call is executed. The next time the plugin is loaded and LOADLAYOUT is called, all of these controls will be loaded again. This can potentially lead to duplicate controls being created if no check is made prior to calling LOADLAYOUT with a specific filename. To avoid this situation you should always call LOADLAYOUT once only.

It is best practice to give each control a name in the Panel Designer (by right-clicking the control, choosing "Set Properties" and specifying a name). When a control is created it is given a unique control ID (analogous to a win32 control's HWND). This ID is then used to communicate with the control, for example when changing the caption text using setcaption. As Brass creates each control it checks to ensure the control ID is unique and, if it isn't, the ID is changed. When creating controls at runtime (for example by using createbutton or createlistbox), the actual control ID of the new control is returned to the plugin code making it easy to keep track of what control has what ID. However because controls created with the Panel Designer are managed internally by Brass, the plugin code has no way to retrieve the control ID of a specific control - especially if Brass has altered the ID to ensure it is unique. Although the "Set Properties" window allows you to specify a control ID this is only a suggestion to Brass and is not guaranteed to remain the same when the plugin is run.

To resolve this problem you may communicate with your controls by name. Once you have specified a name for a control in the Panel Designer (by right-clicking the control, choosing "Set Properties" and specifying a name), you can use the idfromname statement to retrieve it's control ID.

 

Parameters

LayoutFile

Optional, for expert plugin developers only. Brass will load the specified file and insert the layout into the current panel layout.

 

Return Value

The number of controls successfully loaded and inserted into the panel if the loading process succeeded, or -1 if loading failed. You should always check for a loading failure as it will indicate your panel has no visible controls. Consider alerting the user through the drawtext statement or similar, as no static text controls will be available.

Example Code

Assuming a layout has been created with the Panel Designer, the following code is a complete plugin that will load the controls and enable the 100% Configuration System.

function Init()
{
    // Load the user's layout, or the default layout if no custom layout exists
    loadlayout();
}

function Shutdown()
{
    // Save the current layout ready for the next time the user loads the plugin
    savelayout();
}