SkinStudio
GUI WIDGETS


The Idea

With the appearance of SkinStudio Stardock introduces the new, easy way of creating complex skins: skin parts and GUI widgets importing. This document explains the idea and method of creation of a widget. Previously skinners had to create their own skins by compromising on either time or skin complexity. Sure, we all love to create fancy frames, but most of us do not feel happy thinking of creating scrollbars, checkboxes and all the tiny, little pieces to make the skin look really good. Here's where the guiwigets come in handy. Widgets are just GUI pieces (scrollbars, progress bars, frames, title bar buttons, push buttons, menus, etc.) published by skin authors so that you can easily insert them into your skin. One could compare them to the DesktopX objects.


Sample widgets from SkinStudio Enhanced

Here you can download the sample widgets that comes with Skinstudio Enhanced. Click to download the sample widget code.




Specification


First of all let me say that creating a Widget is really simple. To create a widget, all you have to do is open the skin in SkinStudio select the section you want to export and Select "Export branch as Widget" from the File menu. The Exporting process is described in the separate tutorial, so here we will concentrate on the file format specification.

Basically a widget is a uis file but limited to a few sections concerning the feature we want to have encapsulated. A widget may be anything... A colour scheme, scrollbars, fully featured taskbar (with startbutton, taskbar buttons and grips in it) or even as small as a single checkbox (which is a part of [Buttons] section). So the widget is actually quite powerful. Now let's see what you can do with the generated file or maybe let's pretend we're generating the file from scratch.

The most important part of a widget is the following section:

[WidgetInfo]

For now this is the only section that differs gui widget from a regular skin.

The only attribute required in the section for the widget to work is:

WidgetName = My first widget

That is all that is really needed for the widget to work.

Ok, what would be the point of creating a widget if no-one knows you created it? Surely you are proud of what you've done. You could spray it on the walls all over your town... or just put it in the following attributes:

AuthorName = Stardock Net, Inc.
AuthorEmail = myemail@stardock.com
AuthorNote = Designed by Adam. Modifications by Kris and Brad (Frogboy).
AuthorURL = http://www.skinstudio.net

I don't think the above attributes need any further comments, so now let's make your cool widget as tempting as it deserves to be. To do this just place paint an image presenting it's features (the image is maximum 300 pixels wide and 100 pixels high), save the image in the widget folder and put its name in the following attribute:

WidgetPreview = mighty_preview.bmp

Sure thing, you spent a lot of time creating it, so "why" you think "should anyone take the credit when he just creates a skin mostly based on my widget? Can I at least grab part of the splendor of such a skin?". Of course! Every imported widget generates a [WidgetInfo#] section in the skin it's imported to. where # stands for a first available number. So the first imported widget it will generate [WidgetInfo0] section in the skin... and so on. So now every user can admire your work when they open the skinBut wait... you think your work is worth more than just a note? You don't want the skin authors to redistribute your images and code? No problem. Add the following attributes to the [WidgetInfo] section

RedistributionAllowed = 0
WidgetImportInfo = You are not allowed to distribute the skin containing this widget.

Now this requires some more explanation. the "RedistributionAllowed" attribute does not really block the publishing of such a skin... but when the import is performed a skin author is informed that you do not agree to the redistribution of their skin if it contains your work. Available Values are "0" and "1" (0 stands for NO, 1 is YES). If you add the "WidgetImportInfo" to the widget a skin author will see your customized warning instead of default SkinStudio warning. The info will be also shown if the "RedistributionAllowed" is set to 1, but it will only show as a friendly info, a tip for the author, while when the "RedistributionAllowed" is set to 0 the author will have the choice between importing your widget or not importing it.

Ok, so you probably wonder now what is imported and how. As we said, a GUI widget is a part of a skin and as such it can contain any info that can be placed in a well formed skin. Of course, it does not have to be a complete skin. First of all it should not contain the [TitlebarSkin] section (but if it does, the section will be ignored when imported). Importing the widget simply copies (by default) all the attributes in all sections (except the [TitlebarSkin] and [WidgetInfo]) into the skin. The images are also copied based on SkinStudio's knowledge of the attributes format. The images should not contain the folder name relative to WB folder (like in the regular skin eg. maxwb\top.bmp) but if it does, SkinStudio will strip it away (to make it easier for you to convert a skin into widget). Also each section can contain a widget-specific attribute:

WidgetAction = ...

The actions that can be performed for each sections are:

  • REPLACE - (the default action) Causes all the attributes in the corresponding skin section to be replaced with the ones existing in the widget, while all attributes not found in the widget will be deleted.
  • UPDATE - Attributes existing already will be updated, and the atributes not existing in the skin will be added to it. The skin attributes that does not exist in the widget will be left untouched.
  • APPEND - Existing attributes will remain unchanged (only the attributes that does not exist in the skin will be appended)
  • DELETE - The section will be deleted.

You may wonder why would anyone want to DELETE a section... In fact it's the only way to create a widget convertin a "Basic language skin" into an "Advanced language skin" and an "Advanced skin" back into a "Basic skin".

eg.:

[MenuItem]
Tile=0
BottomHeight=5
TopHeight=2
LeftWidth=32
RightWidth=4
Image=tool222.bmp
WidgetAction=REPLACE

The guiwidget format is open for suggestions - please feel free to discuss it at the SkinStudio newsgroups:



this page was last modified on: