Brass SSE Developer Guide - Designing Your Panel
Skip down to the FAQ
You know what you want your plugin to do, but what
about how it looks?
A Sample Plugin
If you're one of those people who prefers to play
with stuff instead of read the docs we have the perfect download
for you. The ZIP file below contains a normal plugin pack (UIDEMO.SSP).
Install the SSP into Brass as normal (use the "File" -
"Install New Plugin" option), then run the plugin. You'll
see a sample of each control in the plugin panel.
You can enable Design Mode through the tray menu,
or by double clicking "UIDemo" in the Brass Active Plugins
list. Play around and see what you can do.
When you're ready, unload the plugin and open SSEdit.
Browse to the <Brass Install Folder>\SSE\UIDemo folder and
open the "UIDemo.ssn" plugin source file. Amazingly there
are only 2 lines of code! Open the Panel Designer ("View"
- "Panel Designer") and you can see the default layout.
Go ahead - play around with it!
Download UIDemo.zip here
So how do I design my plugin's
display?
One of the most powerful features of Brass is the
100% Configuration System. Unlike any other application, Brass allows
you to redesign plugins exactly as you want. All you have to do
is click, drag and drop!
For a demonstration of the 100% Configuration System,
visit the media page.
SSEdit includes a fully featured panel designer that lets you create
the perfect layout for your plugin!
If you've already played with Brass plugins
you might be wondering when you should use the Panel Designer,
and when you should use the dynamic control creation statements
such as createbutton or createlistbox. There is a comprehensive
answer in the FAQ section at the end of this page.
A little background
The entire idea of Brass plugins is that they are configurable.
When someone downloads a plugin they should be able to alter its
appearance as they want, simply by pointing and clicking.
Normally when a program is being developed the user interface is
"fixed". In other words, however the programmer lays out
the user interface is how it will stay forever. But with Brass plugins
you actually specify the default layout - how your plugin will look
when it's first loaded. It's then up to the user if they want to
keep your design or change it entirely.
Using the Panel Designer
To start designing your plugin's layout, create a new plugin source
document ("File" - "New" in SSEdit) and click
the Panel Designer icon on the toolbar ( 
). The Panel Designer pops up, and you can start creating your layout
immediately.
Here's a screenshot of an example layout.
At the top of the window you have your control selection, and at
the bottom is your design canvas. To draw a new control simply click
the control icon, move the mouse to the canvas, hold down the left
mouse button and drag. A rubber band will appear to show the size
of your new control. Release the mouse button and the control will
be created.
You can left click on a control and drag it to a new position,
or use the blue resize handle in the bottom right of a control to
resize it. Right clicking a control displays a context menu of all
the available options for the control.
You might think that the design canvas (the chequered area at the
bottom of the window) is a bit too small for your liking. If so,
simply resize it with the resize handle at the bottom right of the
window. It's important to remember that the canvas size is purely
there to help you design your panel - it's not saved to your plugin's
layout. Plugin display panels can be resized when the plugin is
running in Brass, so if you want to specify a width and height for
your panel you should use the FirstLaunch
handler.
Managing Controls
Play around with the Panel Designer for a few minutes and you'll
quickly see how it works. As you move the mouse over a control it
becomes active, and a grey panel is drawn behind the control.
Active controls also have yellow halos around them. The halo signifies
an area of a control that can be changed. Simple controls, like
buttons or images, have a single halo around their outside edge
(take a look at the screenshot above for an example). This indicates
that the control itself can be dragged to a new position on the
canvas, or resized.
Complex controls, like the listbox, editbox and memobox, have multiple
halos. Here's a standard memobox when activated:
A memobox has one halo around the outside edge, one halo in the
middle, and a resize handle on the scrollbar. The outside edge halo
signifies the control can be dragged and resized, but what about
that inner halo?
The inside halo is the text bounding rectangle. This rectangle
defines the area in which all text is drawn, and it's the same property
that's configured using setmemoboxtextrect.
If you set some default text and look at the control again, this
is what you'll see:
You can reposition this bounding rectange inside the memobox by
clicking and dragging it, or by using the resize handle in its bottom
right corner. As you drag it around it will automatically resize
itself to fit the available space.
Now is a great time to show you one more incredible feature of
the 100% Configuration System. Move the mouse over the middle of
the scrollbar, click and hold the left mouse button, and drag the
scrollbar quickly to the left side of the memobox. Amazing, huh!
As you drag the scrollbar across the control, the
text bounding rectangle auto-resizes itself. But as soon as you
move over halfway across the bounding rectangle, the scrollbar automatically
flips itself to the other side of the control! We don't call it
Amazing Brass for nothing!
Control Properties
All controls have their own individual properties,
as well as the default ones that apply to all controls. Right clicking
a control will bring up a context menu of all the available options.
The memobox is quite a complex control so it has a lot of options.
Most are self-explanatory so we'll only cover the important ones
that relate to all controls here.
Restyle Control and Set Scrollbar Component Sizes
are discussed on the control skinning
page. Note that if you restyle a control so that it's invisible
(you'll be warned by the Panel Designer if you do this!) then a
 icon will
be placed in the middle of the control. You might have a hard time
finding it otherwise :)
Switch States allows you to quickly check how the alternate
states of controls will look. For example, a button control has
a normal state and a clicked state. This option toggles between
the 2 states, it's useful for testing how your control design will
look.
Set Default Text allows you to set the default text that
appears in a control. This is handy if your plugin wants to request
user input (in, for example, an editbox) but also wants to provide
a sensible default option. Users of your plugin can change the default
text to anything they want using the 100% Configuration System,
so don't worry that you're forcing a permanent default here.
Hide Control sets a flag that tells Brass to create your
control, but to keep it invisible. You can then use the showcontrol
statement in your plugin code to make it visible. When you hide
a control the Panel Designer will place a 
icon in the top left to signify the control will be hidden when
the layout is used in Brass.
Disable Control sets a flag that tells Brass not to pass
on any events (normally user input, such as mouse clicks or key
presses) to the control. You can use the enablecontrol
statement in your plugin code to reenable the control. When you
disable a control the Panel Designer will place a 
icon in the top left to signify the control will be disabled.
Manual Size/Position Entry allows you to set a precise pixel
position (relative to the top left corner of the panel, which is
X: 0, Y: 0) and pixel width for your control.
Set Properties is probably the most important option for
any control. Selecting this option displays the following dialog:
This is how your code communicates with the control.
Please read the following section very
carefully, it's important!
As you should know from the User Interface
reference, the Control ID is a unique ID number assigned to
each control. This number is how you tell Brass which control you're
working with when using the UI statements, such as setcaption.
However, there's a bit of a hitch.
When you create controls at runtime (using statements like createbutton
and createeditbox), Brass
checks the control ID you supply to make sure it's unique. If another
control is already using that ID Brass will find the next free ID
and return it to you. In other words, the control ID you give Brass
is only a suggestion.
Unfortunately when you use the Panel Designer you're creating the
controls and using them without any feedback from Brass. You simply
call loadlayout once and all
your controls are magically created for you. If Brass finds 2 controls
with the same control ID, it has no way to tell your plugin code
that it had to renumber one of the controls. This is a bit of a
problem because if your plugin code is expecting a button at ID
4 but, because of an ID conflict, there's actually an image control
at ID 4, (a) you're going to have lost your button as you won't
know what its new ID is, and (b) the plugin code won't be able to
work with the image control because it will think it's a button.
In case you're wondering, yes it's definitely
possible to be very careful with the control IDs you use and
to assign unique IDs manually. It's a bit more work though as
you'll have to keep track of every control, and it's not as
friendly as giving controls a name.
To solve this problem you can assign each control a friendly name,
then use that name to communicate with the control. Simply type
a unique but easy to remember name into the "Control Name"
field, then use the idfromname
statement in your plugin code whenever you need a control ID.
Using friendly names for your controls allows you to leave all
the control ID's set to 1. Brass will load the layout, see that
all the controls have the same ID number, reassign them unique numbers
and then correctly assign the right friendly names to the right
controls. Hey presto, no more worrying about unique control IDs!
Linking Layouts with Code
When you're happy with your default layout simply click the OK
button. The Panel Designer will link your layout with your plugin
automatically; when you save your plugin code the layout will be
saved too. When you deploy your code to Brass for testing (using
the Run in Brass option or the 
button) the default layout will be deployed as well.
After clicking OK you'll be returned to your plugin code in the
main SSEdit window, where you'll see this message.
The loadlayout() call tells
Brass to load the layout you just designed, or, if the user of the
plugin has altered your default layout, Brass will load the custom
layout automatically. The savelayout()
call tells Brass to save the layout of the panel ready to be used
the next time the plugin is loaded.
Simply follow the instructions in the messagebox, and your plugin
code should look like this:
That's really all you need for the 100% Configuration System to
work - 2 lines of code! The loadlayout()
call should usually be the very first statement in your Init handler,
and the savelayout() call
should be the very last statement in your Shutdown handler.
One important point to remember is how the 100% Configuration System
stores your layout. Each time you test your plugin in Brass (using
the
button) the default layout will be deployed as well. Remember that
you've added a loadlayout()
call to your Init handler, and a savelayout()
call to your Shutdown handler? When you unload your plugin and savelayout()
is called, Brass will write your personal layout to SSE\<PluginName>\<Username>_layout.sld.
This is how Brass "remembers" the 100% Configuration
layout for each user when your plugin is running normally. But,
when you're coding your plugin, Brass will always discard your personal
layout each time you test your plugin using the
button. This is in case you made any changes to the default layout
- if your personal layout was used, you'd never see the changes.
Don't worry though, when you use your plugin "for real"
(ie: by loading/unloading it in Brass rather than through SSEdit),
your layout wll be saved normally.
Panel Designer
FAQ
Using the Panel Designer is intuitive, but there are a few important
questions you'll probably have.
Q. What is the chequered grey background for?
Just like in Paintshop Pro, this background signifies a transparent
panel. Wherever you see this background, anything underneath the
panel will show through when it's running in Brass.
Q. What is "Ideal Width" and "Ideal
Height"?
Unlike normal programs you don't specify fixed values for your
plugin's dimensions. In your plugin's FirstLaunch
handler you can set the default width and height of the plugin,
but the user is of course free to resize it however they want. The
Ideal Width and Height values tell you the minimum dimensions your
panel should be by default to ensure all the controls you have drawn
will fit in it.
In this screenshot you can see the Ideal Width and Ideal Height
are equal to the bottom right of the memobox control, which is the
furthest right and down from the top left of the canvas.
Q. The canvas area is too small for my panel,
what do I do?
The entire Panel Designer window can be resized. Simply click on
the resize handle at the bottom right and drag it out as large as
you need. Remember - the size of the canvas
is completely ignored by SSEdit, you must set your plugin's
default width and height in the FirstLaunch
handler. If you used the New Plugin Wizard to create your plugin,
the wizard can add this code for you automatically.
Q. When I clicked "OK" my panel layout
vanished and I can't find it. What do I do?
SSEdit links the panel layout to your plugin code automatically.
When you use the Save option in SSEdit, your code and your layout
will be saved at the same time. Try it - create a layout, close
the Panel Designer, save your plugin then open the Panel Designer
again. Your layout will be restored.
Q. So what are the Load and Save options in the
Panel Designer window for?
Sometimes you might create a layout you want to keep for future
use, or want to store separate from the plugin. In this case you
can use the Save option to export the layout to a file. Then in
future, when you want to use a saved layout, you can use the Load
option to import it. Most of the time you'll never need these options,
so don't worry about them. Just remember that once you click OK
to the Panel Designer window your layout is automatically stored
with your plugin code.
Q. I set a background image/colour, but it only
appears in the Panel Designer and not when my plugin runs in Brass.
Why?
Brass allows users to choose their own background images and colours
for plugins. The background options in the Panel Designer are purely
there to help you see how your layout will look with a specific
background. If you want to set a specific background for your plugin
you should use the panel statements
in the FirstLaunch handler.
Q. How do I use this panel layout system in my
plugin?
Simply draw your layout and OK the Panel Designer. Then add a call
to loadlayout in your Init handler
and a call to savelayout in your Shutdown
handler (if you used the New Plugin Wizard, SSEdit can add this
code for you). Compile your plugin and that's it! Brass handles
everything else.
Q. How do I distribute the default layout with
my plugin?
When you use the Pack Creator to make your plugin's SSP, the default
layout is automatically generated and included. You'll also notice
that any resources you used in the Panel Designer (for example,
custom skinning images for controls) will be included as resources.
Make sure you don't get any resource conflicts, the Pack Creator
will warn you if you do.
There is a detailed explanation on how the Panel Designer and the
Pack Creator work together at this page.
Q. When do I use the Panel Designer, and when
do I use the dynamic creation statements?
If you've played with Brass plugins already, or maybe browsed the
developer guide, you might be wondering when you should use the
Panel Designer to create your layout and when you should use the
dynamic control creation statements such as createbutton
or createlistbox. After
all, they both appear to do the same thing, right?
Not exactly! Most of the time your plugin interface will be exactly
the same - you'll have the same set of controls which do pretty
much the same thing every time the plugin is run. In this case you
should use the Panel Designer.
However sometimes you'll want to create a plugin that adds and
removes controls from its display panel "dynamically".
A great example of this is the Launcher
plugin. Because you can add and remove buttons from the Launcher
plugin whenever you want, it's display isn't "fixed".
Maybe today the Launcher plugin has 7 buttons, but tomorrow it might
only have 4. In this case you would want to use dynamic control
creation.
When creating your plugin, ask yourself this question: "Will
these controls always be present in the plugin display panel?".
If the answer is "yes", use the Panel Designer. If the
answer is "no", use dynamic control creation.
In case you're wondering, dynamically created controls are specifically
excluded from the 100% Configuration System. Because they are dynamically
created, Brass can't be sure that those same controls will be created
the next time your plugin runs. So to avoid any problems Brass simply
doesn't bother saving them to your personal layout file when savelayout()
is called.
Q. I created a layout with the Panel Designer,
and added some skinned controls using my own images. When I went
into the Pack Creator I accidentally deleted all the resources -
all my skinning images - that the Panel Designer added for me! What
do I do?
Simple! First, if your resource list is completely screwed up and
you want to start from fresh, you can either delete each resource
manually in the Pack Creator dialog or delete the .res file stored
with your plugin's .SSN.
To recover all your resources just open the Panel Designer then
click OK to close it again. SSEdit will automatically check the
images you used in the Panel Designer to see if they are already
in your resource list. If they're not, they'll be added again. 100%
automatic!
|
