Welcome

CustomBar is a uniquely flexible "appbar" application. By using CustomBar, you can have easy access to your most commonly used computer tasks and information, all on a tiny bar similiar to the tasbkar. The program comes with a wealth of built-in functionality for accomplishing common things, such as viewing what song is playing, searching your favorite search engine, or emptying the recycle bin.

In addition to built-in features that allow it to be used straight out of the box, CustomBar also has very powerful prefab, plugin, and skin functionality. These three features allow CustomBar's appearance and functionality to be tweaked almost limitlessly.

The documentation in this manual will guide through the use of CustomBar. The manual also contains significant information on how to get started with extending CustomBar. You may wish to check www.custombar.net for newer versions of CustomBar and CustomBar documentation.


Lizardsoft End User Software License Agreement

IMPORTANT--READ THESE TERMS CAREFULLY BEFORE DOWNLOADING THIS SOFTWARE. BY DOWNLOADING OR USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LICENSE AGREEMENT, THAT YOU UNDERSTAND IT, AND THAT YOU AGREE TO BE BOUND BY ITS TERMS. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT, PROMPTLY EXIT THIS PAGE WITHOUT DOWNLOADING THE SOFTWARE. THE PURCHASE OF A SOFTWARE KEY IS REQUIRED FOR USE OF THE SOFTWARE AFTER THE THIRTY (30)-DAY TRIAL PERIOD.

1. Grant of License for Registered Users
Lizardsoft grants you a non-exclusive, non-transferable license to use the Software with which this license is distributed ("Custombar"), including any documentation files accompanying the Software on a single server (if the Software is server based) or personal computer to support up to the number of simultaneous users for which you have paid the license fee, and to make one backup copy of the Software, provided that: (i) the Software is installed on only one server or personal computer; (ii) the Software is NOT modified; (iii) all copyright notices are maintained on the Software; and (iv) you agree to be bound by the terms of this License Agreement. The Software and Documentation shall be used only by you, only for your own personal or internal business use and not in the operation of a service bureau or for the benefit of any other person or entity.

2. Ownership
You have no ownership rights in the Software. Rather, you have a license to use the Software as long as this License Agreement remains in full force and effect. Ownership of the Software, Documentation and all intellectual property rights therein shall remain at all times with Lizardsoft. Any other use of the Software by any person, business, corporation, government organization or any other entity is strictly forbidden and is a violation of this License Agreement.

3. Copyright
The Software and Documentation contain material that is protected by Canadian Copyright Law and trade secret law, and by international treaty provisions. All rights not granted to you herein are expressly reserved by Lizardsoft. You may not remove any proprietary notice of Lizardsoft from any copy of the Software or Documentation.

4. Restrictions
You may not publish, display, disclose, rent, lease, modify, loan, distribute, or create derivative works based on the Software or any part thereof. You may not reverse engineer, decompile, translate, adapt, or disassemble the Software, nor shall you attempt to create the source code from the object code for the Software. You may transfer the Software to other computers you own as long as you only use it on one computer at a time.

5. Confidentiality
You acknowledge that the Software contains proprietary trade secrets of Lizardsoft and you hereby agree to maintain the confidentiality of the Software using at least as great a degree of care as you use to maintain the confidentiality of your own most confidential information. You agree to reasonably communicate the terms and conditions of this Software License Agreement to those persons employed by you who come into contact with the Software, and to use reasonable best efforts to ensure their compliance with such terms and conditions, including, without limitation, not knowingly permitting such persons to use any portion of the Program for the purpose of deriving the source code of the Program or defeating the Key.

6. Limited Warranty
Lizardsoft WARRANTS FOR A PERIOD OF THIRTY (30) DAYS AFTER PURCHASE THAT THE SOFTWARE WILL OPERATE SUBSTANTIALLY IN ACCORDANCE WITH THE DOCUMENTATION. SHOULD THE SOFTWARE NOT SO OPERATE, YOUR EXCLUSIVE REMEDY, AND Lizardsoft's SOLE OBLIGATION UNDER THIS WARRANTY, SHALL BE, AT Lizardsoft's SOLE DISCRETION, CORRECTION OF THE DEFECT OR REFUND OF THE PURCHASE PRICE PAID FOR THE SOFTWARE. ANY USE BY YOU OF THE SOFTWARE IS AT YOUR OWN RISK. THIS LIMITED WARRANTY IS THE ONLY WARRANTY PROVIDED BY Lizardsoft REGARDING THE SOFTWARE. EXCEPT FOR THE LIMITED WARRANTY ABOVE, THE SOFTWARE IS PROVIDED "AS IS." TO THE MAXIMUM EXTENT PERMITTED BY LAW, Lizardsoft DISCLAIMS ALL OTHER WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Lizardsoft DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET ANY REQUIREMENTS OR NEEDS YOU MAY HAVE, OR THAT THE SOFTWARE WILL OPERATE ERROR FREE, OR IN AN UNINTERRUPTED FASHION, OR THAT ANY DEFECTS OR ERRORS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE IS COMPATIBLE WITH ANY PARTICULAR PLATFORM. SOME JURISDICTIONS DO NOT ALLOW THE WAIVER OR EXCLUSION OF IMPLIED WARRANTIES SO THEY MAY NOT APPLY TO YOU.

7. Limitation of Liability
IN NO EVENT WILL Lizardsoft BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, WITHOUT LIMITATION, INDIRECT, SPECIAL, PUNITIVE, OR EXEMPLARY DAMAGES FOR LOSS OF BUSINESS, LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION) ARISING OUT OF THE USE OF OR INABILITY TO USE THE PROGRAM, OR FOR ANY CLAIM BY ANY OTHER PARTY, EVEN IF Lizardsoft HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Lizardsoft's AGGREGATE LIABILITY WITH RESPECT TO ITS OBLIGATIONS UNDER THIS AGREEMENT OR OTHERWISE WITH RESPECT TO THE SOFTWARE AND DOCUMENTATION OR OTHERWISE SHALL NOT EXCEED THE AMOUNT OF THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE AND DOCUMENTATION. BECAUSE SOME STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

8. Export Restrictions
THIS LICENSE AGREEMENT IS EXPRESSLY MADE SUBJECT TO ANY LAWS, REGULATIONS, ORDERS, OR OTHER RESTRICTIONS ON THE EXPORT FROM Canada OF THE SOFTWARE OR INFORMATION ABOUT SUCH SOFTWARE WHICH MAY BE IMPOSED FROM TIME TO TIME BY THE GOVERNMENT OF Canada. YOU SHALL NOT EXPORT THE SOFTWARE, DOCUMENTATION, OR INFORMATION ABOUT THE SOFTWARE AND DOCUMENTATION WITHOUT CONSENT OF Lizardsoft AND COMPLIANCE WITH SUCH LAWS, REGULATIONS, ORDERS, OR OTHER RESTRICTIONS.

9. Termination
This License Agreement is effective until it is terminated. You may terminate this License Agreement at any time by destroying or returning to Lizardsoft all copies of the Software and Documentation in your possession or under your control. Lizardsoft may terminate this License Agreement for any reason, including, but not limited to, if Lizardsoft finds that you have violated any of the terms of this License Agreement. Upon notification of termination, you agree to destroy or return to Lizardsoft all copies of the Software and Documentation and to certify in writing that all known copies, including backup copies, have been destroyed. All provisions relating to confidentiality, proprietary rights, and non-disclosure shall survive the termination of this Software License Agreement.

10. General
This License Agreement shall be construed, interpreted and governed by the laws of Canada without regard to conflicts of law provisions thereof. The exclusive forum for any disputes arising out of or relating to this License Agreement shall be an appropriate court sitting in Ontario, Canada. This License Agreement shall constitute the entire Agreement between the parties hereto. Any waiver or modification of this License Agreement shall only be effective if it is in writing and signed by both parties hereto. If any part of this License Agreement is found invalid or unenforceable by a court of competent jurisdiction, the remainder of this License Agreement shall be interpreted so as to reasonably effect the intention of the parties.

11. Updates, Patches and Upgrades
If the software and related documentation are provided as an upgrade, patch or update to an earlier licensed release of the software, then you must have a valid license to operate such earlier release of the same version as the upgrade, update or patch to install or use the upgrade, update or patch. All software being upgraded, updated or patched is deemed to be part of the software and is subject to this Agreement.

12. Contact
Lizardsoft
Main address:
PO Box 37002 1005 Ottawa St. N Kitchener, ON Canada N2A 2H0
Website: http://www.lizardsoft.com
E-mail: software@lizardsoft.com


Version History

Version 1.0 - July 1, 2004

Initial release of CustomBar.


Credits

DESIGN AND DEVELOPMENT

Matt Inglot

DOCUMENTATION

Matt Inglot

LEAD TESTERS

Thomas "Zenny" Amaro
Jason Aylen
Brian "bork" Bugh
Mick "Keshik" Clark
Halo (www.4inthemorn.com)
Jonathan Lee
Aaron Malone
Rycon Payne
John "ErIog" Rozewicki
Tyler Shortt
SonnyD64

BETA TESTERS

Thomas "Zenny" Amaro
Jason Aylen
Rohan Buckland
Brian "bork" Bugh
Mick "Keshik" Clark
Victor Da Luz
Ian Douglas
Petar Drankarov
Travis Elijah
Chris Erickson
Melissa Fehr
Jeff Greco
Halo (www.4inthemorn.com)
Brian Kraus
Scott Kroll
Kyle
Nathan "vrunt" Lamagna
Brian LaPota
Jonathan Lee
Greg "gleffler" Leffler
James Little
LordIcarus
Aaron Malone
Joel Martinez
Rycon Payne
Phuc (John) Hoang Pham
Kevin "lat" Rawls
John "ErIog" Rozewicki
Tyler Shortt
John Sideserf
SonnyD64
Adam Swift
Jason Szkola
Daniel S. Tarkenton
Turin
Ted Vossen
Heng Kuan Yen
Zpeef

BETA TESTING MADE POSSIBLE BY

www.betashare.com

SPECIAL THANKS TO

www.codeproject.com
www.gamedev.net
www.dexterity.com

COPYRIGHT

CustomBar is Copyright (C) 2002-2004 Lizardsoft. All rights reserved.


CustomBar User Guide

Welcome to the CustomBar user guide. It is intended to get you familiar with CustomBar's functionality as quickly as possible. Please send any comments and suggestions about this manual to helpfeedback@custombar.net.

Contents:

1. Installation

2. Quick Start

3. Common Issues


Installation

New Installation

Both the full and trial versions of CustomBar come with an installer that makes getting CustomBar setup a snap. After installation, you will have the option of starting CustomBar. This will launch the default bar and allow you to get started with CustomBar right away. In addition to CustomBar, the installation program also installs BarCreator, the editor for CustomBar bars.

Upgrading an Existing Installation

To upgrade your version of CustomBar, simply download the latest trial or full version of CustomBar and run the setup program. The CustomBar installer automatically detects if you have an existing version of CustomBar already installed on your computer and upgrades it appropriately. It will not overwrite any settings files or user-created bars, skins, prefabs, or plugins.

Common Installation Questions

1) Where do I obtain the setup program for the full version of CustomBar?

If you have purchased the full version of CustomBar, you should have received an e-mail with login information for a special customer area of www.custombar.net. This area contains instructions on downloading the full version of CustomBar.If you have misplaced your registration information or otherwise require assistance, please send an e-mail to software@lizardsoft.com and we will be happy to assist you.

If you have not yet purchased CustomBar, you can order quickly and safely online through our www.custombar.net website. A free trial version is available for download there as well.

2) The program is asking me for a registration key. Where do I get one?

The full version of CustomBar requires a registration key to run. If you have purchased CustomBar, you should have received registration information in your e-mail account. If you have misplaced this information or did not receive it, please contact software@lizardsoft.com and we will be happy to assist you.

If you are attempting to download the trial version of CustomBar, please visit the www.custombar.net website.


Quick Start

Introduction

This guide is the fastest way to getting started with CustomBar. After you have read this, you will be able to create your very own customized bar. If you have not yet installed CustomBar, please do so before attempting to follow the steps in this guide.

Running CustomBar

The CustomBar application itself is useless without a bar file to run. Luckily, the CustomBar installation comes with a sample bar that you can use to immediately test the application, and also to have a template for creating your own bar.

To start this sample bar on a fresh installation of CustomBar, you can do one of three things:

1. The installation program gives you the opportunity to launch CustomBar after the installation. Doing so will load the sample bar.

2. By default the sample bar is set to automatically start when CustomBar is run or Windows starts. You can change this behavior in the CustomBar options.

3. The CustomBar installation folder has a folder inside it named Bars\Sample 1\. Double-clicking the Sample 1.tds bar file inside this folder will launch this bar file.

After you have used one of the above methods to run the sample bar, CustomBar should start and part of it should look approximately like this:

Example of sample bar.

If you have difficulty launching the sample bar, please consult the troubleshooting section of this manual.

Getting Acquainted with the Sample Bar

The sample bar comes with a small set of CustomBar features, most of which will work without additional configuration. We will first go over how to use the functionality on this sample bar. Then you will learn how to use BarCreator to customize it to meet your needs.

Every component on a bar is known as a prefab. Prefabs are a collection of scripts and layout definitions that form a nice package. CustomBar comes with a wealth of prefabs, a few of which you are now seeing on your running bar.

The following is a quick rundown of the various functionality that the prefabs on the sample bar offer. CustomBar attempts to pack in as many features as possible into the tiniest possible space; as a result, many elements on the bar provide additional functionality when right-clicked.

Note to Win9x Users: Although CustomBar itself is compatible with Windows 98 or higher, some of the CustomBar prefabs require Windows 2000 or higher. If certain information is not being displayed or features are missing, this is probably the reason.

System Information

The sample bar has two groups of system statistics. All stats labels can be left-clicked to display a summary of system information.

Memory and network information.

Memory Use: this is the total amount of memory in use by the system, including RAM and swap. It is synonymous with the value that is displayed in the task manager of Windows 2000 and higher.

Network Speed: this displays the upload and download rates that your network is currently transferring. This includes internet traffic for users of most high speed internet services, as well as traffic to the local network. Dial-up modem speeds are not displayed.

CPU and system up-time.

Processor Load: this displays the approximate percentage of processing power currently in use. An idle system will typically jump around between 1 and 10% CPU use. This is the same statistic as displayed in the task manager of Windows 2000 and higher systems.

System Uptime: this is simply the amount of days since Windows was last started. You can right-click this display to copy the information to your clipboard.

Internet Search

Search box after right-clicking.

The search box allows you to quickly search your favorite search engine. To use it, simply type your query into the box and press enter. Your default browser will launch with search results.

By right-clicking the edit box, you can access 5 more search boxes (pictured above). Each box can be set to search the website of your choice. You will learn how to do this when we explore the BarCreator editor.

Audio Player

One of CustomBar's most popular prefabs, the audio player is an important tool for any true computer user. At the time of this writing, the player is capable of controlling the Winamp 2 and Winamp 5 audio players. Through a community effort, we are hoping to introduce support for additional audio players.If you find that some features are not working, please try upgrading your version of Winamp.

The following is a description of all the audio player features on the sample bar, from left to right:

Song Title: displays the name of the currently playing song. Left-click to launch or show Winamp, right-click to copy the song title to the clipboard.

Song Time: displays the elapsed and total time of currently playing song. Left-click to launch or show Winamp.

Playback Buttons: the next four buttons allow you to quickly play/pause tracks, as well as to navigate between them. They are the functional equivalent of pressing the corresponding button in your audio player.

Song Menu: the button with the L on it can allow you to display a menu of folders in your song collection, and to play them with a click. For example, if you have your music collection organized by artist and album, you can use this to men to quickly play the album of your choice.

Before this feature will work, you will need to tell the audio player the location of your music folder. This will be covered in the section on using BarCreator.

Volume Control: the V button opens a container with 3 volume sliders. From left to right, they control the following: system volume, system wave volume, and audio player volume.

Open Folder: this opens the Open Folder dialog of your audio player software.

Open File(s): this opens the Open Files dialog of your audio player software.

Additional capabilities, not enabled in the sample bar, are also available. You can enable or disable features of the audio player prefab using BarCreator.

Recycle Bin

Recycle bin after right-clicking.

This is one of two examples on the sample bar of a special shortcut prefab. This recycle bin prefab will open the recycle bin when left-clicked. When right-clicked, it provides a very quick way to empty it.

Launch Browser

Browser shortcut after right-clicking.

This prefab can be used to not only quickly open the default browser, but also to quickly launch a specific url. Left-clicking will simply launch your browser with your home page open. Right-clicking presents an address bar box, complete with auto url-completion, which you can paste in (CTRL-V) or type the address of the site that you wish to visit.

Editing Bars with BarCreator

CustomBar offers many opportunities for customization. The easiest way to make your bar fit your needs is by using the CustomBar editor, known as BarCreator. Through BarCreator you can place and arrange CustomBar prefabs on your bar. Every prefab also contains numerous settings that allow you to tweak the functionality to your liking.

Opening BarCreator

The CustomBar main menu (typically accessed through the left-most button on your bar) allows you to quickly launch BarCreator with your current bar open and ready for editing. You can also access BarCreator through the Start Menu and desktop shortcuts that the CustomBar setup program offers to create.

Go ahead and launch BarCreator. The Quick Start guide assumes that you open the sample bar (\Bars\Sample 1\Sample 1.tds). You may wish to immediately use the Save As button in BarCreator to save the bar to another file, so as to not overwrite the sample bar file.

CustomBar main menu.

Using BarCreator

You should now have BarCreator open, and looking something like this:

BarCreator main screen.

Using BarCreator is fairly straightforward. The Elements on Bar list contains all the prefabs currently on the bar. If you are editing the sample bar, you will see quite a bit already on there. If you have started a new bar, you will initially only have a bar and the CustomBar Menu. The bar cannot be removed, however bars can be added. The arrows to the right of the Element List allow you to change the order of the prefabs on your bar.

Editing Prefab Settings

Every prefab contains a set of settings, which are displayed in the Element Properties box when you select it. Earlier in this guide, we introduced the Audio Player prefab. Unless you happen to keep your music collection in C:\Music\, odds are that the L button on the Audio Player of your bar currently does nothing. To change this, select the Audio Control prefab in the Element List. You will then see a list of settings, including one called Main Music Folder. Change this setting to the location of your music collection:

Set the Music Folder setting of the audio player to the location of your music collection.

To save your changes, you can either use the Save Bar or Launch Bar buttons. In addition to saving your bar file, Launch Bar also launchs (or reloads if it is currently running) your bar. Press Launch Bar and allow your bar to load. Using the L button should now bring up your music folders organized into a menu. If you have a music folder with many sub-folder, you may find that the menu goes off the screen. You can fix this by changing the Music Menu Style setting to Scrolling. This will cause the music menu to be displayed using scrolling instead of columns.

This is a good time to go through the settings of all the elements that are currently on your bar. Feel free to remove any prefabs that you don't wish to have on your bar. You can do this by selecting the prefab you wish to delete and pressing the Remove button.

Adding Prefabs

The sample bar discussed in this guide contains only a small subset of the prefabs that come with CustomBar. The Prefab Gallery, accessed through the Add Item button in BarCreator, lists all the prefabs that are currently available for adding to your bar:

The Prefab Gallery

For easier browsing, prefabs are organized into categories. Each prefab may also have one or more variations (known as styles). For example, the SystemStats.UpTime prefab has Digital and Verbose styles.

Downloading More Prefabs

The CustomBar prefab system was designed from the start to allow other people to create prefabs for CustomBar as well. The prefabs that come with CustomBar use the exact same prefab system that is available to 3rd parties; any prefabs that you download from the internet can be added and edited through BarCreator just like the "built-in" ones. The CustomBar website, located at www.custombar.net, contains a library of 3rd-party prefabs, plugins, and skins that you can download for free.

Creating your own prefabs does not require knowledge of any programming languages. CustomBar's script system, documented in this manual, is all you need. For more advanced customization, you can write plugins, which require C knowledge and allow you to expand the capabilities of CustomBar limitlessly.

Adjusting Prefab Layout

Changing the order that prefabs appear on your bar can be done simply using the two arrows at the top right of the Element List. However, to truly tweak the bar to your liking, you will want to using the layout options that each prefab provides. BarCreator provides prefabs standard layout settings that they may use to allow the user to customize the size and position of the prefab on the bar. You will find the following settings on most prefabs:

Typical layout settings.

These settings allow you to adjust the position, size, and alignment of prefabs on your bar.The most frequently used of these settings are X Offset and Y Offset. These settings control the pixel offset of the prefab from where it would normally appear, and allow you to fine-tune its placing on the bar. The Horizontal Alignment setting is used to control which side of the bar a prefab appears. Height and vertical alignment are generally left as defaults, but can be handy if you have created a bar with a custom size.

Note: prefabs only offer the layout settings that they can provide reasonably. You might find that certain prefabs that might not offer size or positioning settings. What settings are offered are ultimately decided by the prefab author.

Conclusion

That's most of what you need to know in order to use CustomBar. If you are interested in creating skins, prefabs, or plugins, be sure to check out the relevant sections of this manual. For CustomBar discussion, be sure to visit the CustomBar Forums


Common Issues

This section is an attempt to address some of the most common questions and quirks that people may encounter when using CustomBar. Installation questions are covered in the separate installation section.

1) After running a full screen program, my bar gets partially covered by other applications.

This issue exists with some full screen applications in conjunction with the Classical Windows mode in Windows XP or when using an older version of Windows. If this happens to your bar, you can select the Toggle Always on Top option in the bar's main menu. In some rare cases, you may need to select this option more than once. This will restore your bar back to the correct display state.

2) An OpenGL application does not work correctly with CustomBar running.

Problems have been reported with a select few applications that use OpenGL (possibly all using the same engine). This appears to be a general incompatibility between these applications and Windows appbars. It has been found that switching the 3D renderer in the application to Direct3D resolves the problem.

3) The bar remains visible during a full screen application.

At the time of this writing, there are no known problems that result in this behavior. However, with certain applications CustomBar might take a few seconds to disappear. If you do encounter CustomBar not disappearing at all, you can submit a bug at the CustomBar Forums.

4) Some of the system stats incorrectly display '0'.

Your operating system may not support a feature that CustomBar uses to get that particular information. This is mostly true for Windows 98/ME; we recommend using Windows 2000 or higher when running CustomBar.

5) The audio control doesn't work.

The CustomBar AudioControl prefab currently supports Nullsoft Winamp versions 2 and 5. Winamp 3 is not supported. Support for additional players may be incorporated at a future time, particularly if the CustomBar community helps out. Visit the CustomBar Forums if you are looking for the latest information on audio control compatibility.

6) The 'L' button on the audio control does nothing.

The L button displays your music collection as a menu that you can use to quickly load an album. Before this menu will work, you need to tell the AudioControl prefab where your music collection is. You can set this setting by editing your bar in BarCreator.

7) A menu is larger than the screen and gets cut off.

CustomBar prefabs that use menus allow you to specify two modes of menu display. Column mode is more convienent (no need to scroll) but does not work correctly when a menu is larger than can fit on your screen. In this situation you should switch to the more conventional scrolling mode. You can do this by editing your bar in BarCreator, and changing the setting for prefab that you are having trouble with.


CustomBar Skin Creation Manual

CustomBar Skin Creation Manual

Welcome to the CustomBar skin creation manual. This is a great way to get into CustomBar skinning beyond just changing graphics in existing skins. Please send any comments and suggestions about this manual to helpfeedback@custombar.net.

Contents:

1. Getting Started with Skinning

2. Official Skin Specification


Getting Started With Skinning

Introduction

There are several levels of difficulty when creating CustomBar skins. The easiest level, and the absolute best way to get started, is by simply replacing the graphics of an existing skin. Some people may try to understand the skin format and the Skin Specification right away. This is generally a bad idea, as this stuff will be much easier to understand once you have actually dabbled in creating skins.

Creating Your First Skin

So you have decided to create your first CustomBar skin. Start by creating a copy of one of the default CustomBar skins: Original, SilverXP, or WhiteAsh. The skins are located in the Skins folder of your CustomBar folder. Each skin has its own folder, so it is enough to simply copy-paste an existing skin's folder and to rename the copy to the name you wish your skin to have (don't use spaces).

At this point you have a new skin. Since you are new to skinning, it is best to begin by simply editing the skin graphics. Since for now you are not editing the skin's code, you have to fit your skin within the layout of the skin that you copied. This means that you should avoid anything too fancy, such as gargoyle heads on top of containers. To try out your changes select your skin from CustomBar's skin menu in the CustomBar application menu, just like you would any other skin. If the skin doesn't appear there, you may need to close your bar and start it again (unlikely but possible problem).

Congratulations, you have created a new skin. Now it is time to experiment further...

Making Minor Code Modifications

Like most CustomBar data files, skin code consists of TDS files. If you look in the folder of a CustomBar skin, you will see one or more .tds files in addition to the skin graphic files. These files specify details about each skin part, including text color, fonts, graphics sources, and even size recommendations. If you have been following the instructions in this guide, now is the time to open the Edit.tds file. You can do this in any text editor, such as Notepad.

At this point you should see a file that partially resembles an .ini file. Entries exist in it for all three standard edit control skin parts. Among the various settings you will find references to ForeColor. This determines the color of text and is probably the setting you are most itching to change right now. Colors are specified the way same that they are in HTML style sheets. This means that each color value starts with a # sign and is followed by two characters for Red, two characters for Green, and two characters for Blue. Each color component is specified in hexadecimal, so values like #AA0B34 are valid. If hexadecimal is foreign to you, do not fear. You can use a calculator to convert normal 0-255 values to hex. Go ahead and experiment with changing values around, that's the best way to learn!

Getting into the Complex Stuff

If you have followed this guide you should be ready to sink your teeth into creating more complex skins. To learn more about what the various settings do in skin files, and how to create fancier skins, go ahead and read the Skin Specification.


CustomBar Skin Specification 1.2

Introduction

CustomBar provides a powerful skinning system to meet the design goal of allowing it to blend in well with any variety of desktop themes and configurations. CustomBar takes the approach of separating appearance and layout. Skins control only the appearance of bar elements; with the exception of size recommendations, they do not decide the layout of a bar. This separation is key to allowing users to customize their CustomBar as much as possible.

Why the Skin Specification Exists

CustomBar's skin system has features and capabilities that extend beyond CustomBar. It is designed to provide general application skinning functionality, and can be used by more than just CustomBar (BarCreator uses it too for example). In order to make skins created for CustomBar usuable on any bar with properly written prefab, a standard needed to be established. By making your skins comply to the CustomBar Skin Specification, you are making sure that almost any bar configuration is compatible with your skin.

What the Skin Specification Provides

The CustomBar Skin Specification (here on know as the Skin Spec) defines a set of skin parts that prefab developers can expect to exist on any skin. It also explains what each skin part is expected to be used for, and what range of sizes and fonts it should be able to appear well in.

The skin format and a list of recommended fonts are also included. If you have not yet done so, it is strongly recommended that you read the Tutorials section of the Skins Manual before reading the Skin Spec. The tutorials take you through skin creation step by step, while the Skin Spec acts as a reference for skinners that already know the basics of skin creation.


CustomBar Skin Format

Introduction

This document describes the CustomBar Skin Format and the general information that is expected by the CustomBar Skin Specification. To make optimal use of this guide, it is recommended that you have a skin file open that meets the Skin Specification standard.

File Format

CustomBar skins are created using TDSettings, a settings language that is also used by CustomBar prefabs and other CustomBar data files. The knowledge of TDSettings required to create or edit skin files is very minimal. For more information on TDSettings, please see the appropriate documentation.

General Rules

In order for a skin to be considered STANDARD, it must meet the following requirements:

1. ALL skin parts must specify a DefaultWidth and DefaultHeight, EXCEPT for container and bar backgrounds.

2. Only use fonts in the VALID FONT LIST (see end of document)

3. Must include all STANDARD SKIN PARTS and obey their restrictions

Skin Information

Each skin includes a [SKIN] category where information about the skin can be included. Currently, you may include the following information:

Name - name of skin, will be displayed in any skin selection menus

Format - the application and skin spec version skin was created for (see example for correct string)

Author - name of skin author

Email - e-mail through which skin author can be reached

Website - author's website

Description - short 1-5 sentence description of the skin

All information settings are strings. You may choose to omit all but the Format and Name properties from your skin. Below is an example of a proper skin information section:

[SKIN]

Name = "Lizard Skin"
Format = "CustomBar Skin Spec 1.2"
Author = "Lizardsoft"
Email = "software@lizardsoft.com"
Website = "http://www.lizardsoft.com"
Description = "A very fun skin."

Note that the current version of CustomBar doesn't necessarily use all this information. However, by including this information you are making sure your skin is ready for future versions of CustomBar.

Skin Parts

Following the [SKIN] category are one or more categories defining skin parts. These parts are the meat of the skin, and provide information to CustomBar on how to display them and what graphics files to use. Skin part names consist of two parts: the interface element it is meant for and the name of the actual part. eg. Button.Normal or Edit.Tiny. The Skin Spec expects certain part names to exist in all skins. These are listed in Appendix A.

Every skin part specifies a number of properties, such as name, graphics file, recommended sizes, drawing mode, border settings, and font attributes/colors. A skin part can also specify child parts. This is used for complex interface elements such as sliders, which have more than one "piece" (eg. a slider has a rail and a thumb).

The following is an example of the definition of an edit box skin part, complete with borders that size properly to any size:

[@INC]
{SimplePart}

Type = "Edit"
Name = "Normal"

ImageSource = "\.\\edit.bmp"

NormalStart = "[31,00]"

TopLeft = "[00,08,02,10]"
Top = "[05,08,19,10]"
TopRight = "[22,08,24,10]"
Left = "[00,13,02,26]"
Middle = "[05,13,19,26]"
Right = "[22,13,24,26]"
BottomLeft = "[00,29,02,31]"
Bottom = "[05,29,19,31]"
BottomRight = "[22,29,24,31]"

Borders = "[03,01,03,01]"

Transparent = false
TileMiddle = true

Font = "Arial;9;"
ForeColor = "#000000"
BackColor = "#000000"

DefaultWidth = 80
DefaultHeight= 18

The edit.bmp image file referred to above looks as follows:

The Coordinate System

The skin engine requires that skin parts specify a source image from which to draw the part from. It also requires that the part specify which part of the image to use.

The example in the previous section features a large block of pixel coordinates. This may be intimidating, but the good news is that the example goes overboard for the sake of demonstration. In all but the most extreme cases, one to five lines of coordinates need to be specified (Middle, Top, Left, Right, and Bottom are the most common).

Each line of coordinates, such as Middle or Bottom, specify the location of the image to draw for a specific section of the part. This is essential to allowing a single skin part to fit a control that can be any size. Middle is the only required section; the rest of the sections facilitate the drawing of various edges. It is possible to specify any combination of additional edges. If you wish your skin part to only have a top border, you would add a Top property that specifies the coordinates of the top border within your source graphic.

The coordinates specified are in order of left, top, right, bottom. This forms a rectangle that is tiled to fit the area (eg. the top border graphic will be tiled to fit the width of the control being skinned). The coordinates do not have to correspond directly to the pixels in the image. The example above sets the property NormalStart to offset all x coordinates by 31 pixels, and all y coordinates by 0 pixels. The purpose of this powerful feature is described in the next section.

Part States

An interface control may have more than one possible state. For example, you may wish to have a button use a different image when it is pressed or when the mouse is hovering over it.The skin system allows you to accomplish this easily without having to specify an entire set of coordinates for every state that you wish to supply a different image for.

In the example listed in the Skin Parts section above, the property NormalStart is set. Normal is one of several possible part states. Hover and Select are examples of two more states. The xxxStart properties allow you to specify an offset in the image from which the coordinates listed for the part match up with the image for the specified part.

The image above is an example of an image file for a button part. It has been doubled in size for easier viewing. It contains graphics for three different button states: normal, hover, and select. It would be incredibly tedious and unnecessary to have to specify all coordinates for every single state. Note how the three state images are spaced apart evenly vertically. By specifying different start offsets in the image for each of the three states, the button part is able to re-use the list of coordinates for every state.

This is how the button part's coordinate definitions might look:

NormalStart = "[31,12]"
HoverStart = "[31,46]"
SelectStart = "[31,80]"

TopLeft = "[00,00,02,02]"
Top = "[05,00,19,02]"
TopRight = "[22,00,24,02]"
Left = "[00,05,02,18]"
Middle = "[05,05,19,18]"
Right = "[22,05,24,18]"
BottomLeft = "[00,21,02,23]"
Bottom = "[05,21,19,23]"
BottomRight = "[22,21,24,23]"

Only one set of coordinates is used, but by specifying different coordinate offsets for HoverStart and SelectStart, the skin part tells the skin engine to map them to different parts of the image. Note that the sample bitmap shown above is doubled in size for readability purposes. The coordinates would actually match up properly with this image:

Only the NormalStart property is required. For any other state that a control goes in, if a corresponding state is not found in the skin part, the Normal state graphic is used.

Skin Graphics

The image files used in the skin should be included in the same folder as the skin, or inside a sub folder. Officially supported image formats are BMP and PNG. Technically EMF should work as well, and provides some support for using vector graphics. Certain systems may be capable of loading additional formats. The Skin Spec requires that you stick to only the three officially suppported formats to ensure maximum compatibility.

Handling Text

Skin elements can dictate the appearance of text in controls that use them. It is possible to set the font, size, attributes, and color of text within a skin element. Example:

Font = "Arial;9;bold-italic"
ForeColor = "#B14E12"

Text color is set by the ForeColor property. Colors are specified HTML-style, using a # character followed by 6 digits. Every 2 digits represent the hexadecimal value of a color. The colors are in Red, Green, Blue order, so the two left-most digits represent the red component of the color, the next two represent the green component, and the final two represent the blue component. If you do not understand hexadecimal, simply use a calculator to convert decimal RGB values to hex. Most calculators have a special function for doing this.

The font property is set by specifying the facename (see Appendix B for Skin Spec font list), size in pts, and any attributes for the font. Valid attributes are bold, italic, strikeout, and underline. Multiple attributes can be applied by separating them with a '-' character, as demonstrated in the example above. If no attributes are being applied, simply don't specify any.

Note: text information within a skin element is merely a suggestion. Prefabs may specify their own settings to override those that a skin sets, though this happens rarely.

Size Recommendations

The DefaultWidth and DefaultHeight properties can be used to specify the recommended size, in pixels, for the control using the skin element. For some skin elements, particularly glyphs and slider parts, these values are especially important. For other elements, such as normal buttons, they are defaulted to when no size is explicitely set for the control.

The Skin Specification includes a list of size ranges that the Skin Spec skin elements are expected to look good under, as well as recommended default sizes. See Appendix A for this information.


Appendix A: Skin Elements

CustomBar's skin system has features and capabilities that extend beyond CustomBar. It is designed to provide general application skinning functionality, and can be used by more than just CustomBar (BarCreator uses it too for example). In order to make skins created for CustomBar usuable on any bar with properly written prefab, a standard needed to be established. By making your skins comply to the CustomBar Skin Specification, you are making sure that almost any bar configuration is compatible with your skin.

The following is a reference for every standard skin part. These skin parts must be included in every skin in order to work well with every bar. There is no rule against adding your own skin part names as well. This is particularly useful if you are making the skin for yourself and have also made your own prefabs that make use of these custom parts.

Bar.Normal
Button.Icon
Button.MainMenu
Button.Normal
Button.Player
Button.PlayerStatic
Button.Transparent
Container.Normal
Container.Transparent
Edit.Normal
Edit.Tiny
Edit.Transparent
Image.SeparatorH
Label.Heading
Label.Monospace
Label.Normal
Label.SongInfo
Label.SongInfoStatic
Label.Transparent
Slider.Vertical

The above are all exact typeface names that can be specified directly as spelled in this guide.


.Normal

CustomBar: Skin Reference

Bar.Normal

Background used for bars. If adding any sort of gradients, keep in mind that the height of the bar is not guarenteed to be 18 pixels. Any sort of gradient you add has to look good on bar heights that range from 16 to 28 pixels!

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | 500px
Minimum Height: | 16px
Maximum Width: | unlimited
Maximum Height: | 28px


.Icon

CustomBar: Skin Reference

Button.Icon

Used in situations where the button is expected to have an icon image on it. Although icon images are generally 16x16px, the button can be expected to be larger in some circumstances and should look good with a 32x32px icon in it.

Default Width Range: | min 16px, max 18px
Default Height Range: | min 12px, max 18px
Minimum Width: | 16px
Minimum Height: | 16px
Maximum Width: | unlimited
Maximum Height: | unlimited


.MainMenu

CustomBar: Skin Reference

Button.MainMenu

This is used only by the Menus.CustomBar prefab, which shows the bar's main menu. The button can be expected to be DefaultWidth and DefaultHeight, provided that the DefaultWidth and DefaultHeight you set are within the allowed range. If you have a "logo" for your skin, this is the place to put it.

Default Width Range: | min 2px, max 18px
Default Height Range: | min 2px, max 18px
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.Normal

CustomBar: Skin Reference

Button.Normal

Normal button that looks aesthetically pleasing on both containers and bars. Used by many prefabs. Must look good with images or text in it. The CustomBar:SkinTest prefab is an example of a prefab that uses Button.Normal.

Default Width Range: | min 16px, max 18px
Default Height Range: | min 12px, max 18px
Minimum Width: | 12px
Minimum Height: | 12px
Maximum Width: | unlimited
Maximum Height: | unlimited


.Player

CustomBar: Skin Reference

Button.Player

This is an audio player button that must look good even at tiny sizes. Some prefabs specify dimensions for audio buttons and some use the skin default. Prefabs that specify sizes for audio buttons should use this skin part, instead of Button.PlayerStatic. DefaultWidth and DefaultHeight must still be specified.

Default Width Range: | min 4px, max 20px
Default Height Range: | min 2px, max 18px
Minimum Width: | 9px
Minimum Height: | 9px
Maximum Width: | unlimited
Maximum Height: | unlimited


.PlayerStatic

CustomBar: Skin Reference

Button.PlayerStatic

This skin part is used specifically by audio control prefabs. It exists because many skins like to have special graphics for audio control parts and because almost everyone uses some sort of audio control prefab. This version of an audio button is only used by prefabs that do not specify a button size. Thus you can expect that the DefaultWidth and DefaultHeight specified by you will be the dimensions of the buttons as they appear.

Default Width Range: | min 4px, max 20px
Default Height Range: | min 2px, max 18px
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.Transparent

CustomBar: Skin Reference

Button.Transparent

A button that must be entirely transparent in any state. No width or height rules exist. Font should match Button.Normal. It is recommended that you examine the default WhiteAsh skin for examples.

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.Normal

CustomBar: Skin Reference

Container.Normal

Used by normal containers. Containers are any of the windows that pop-up attached to the bar, such as the list of search boxes, the volume container, and the address bar you get when you right-click IE.

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | 32px
Minimum Height: | 16px
Maximum Width: | unlimited
Maximum Height: | unlimited


.Transparent

CustomBar: Skin Reference

Container.Transparent

A container that must be entirely transparent in any state. No width or height rules exist. Font should match Container.Normal. It is recommended that you examine the default WhiteAsh skin for examples.

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.Normal

CustomBar: Skin Reference

Edit.Normal

This is a regular edit box, similiar to the kind you normally see in windows. Since bars are generally tiny, edit boxes that use this skin element are generally found on larger containers. The Organization:Notepad prefab is a good example. Font size should be in the area of 9 or 10pt.

Default Width Range: | min 80px, max 100px
Default Height Range: | min 18px, max 20px
Minimum Width: | 16px
Minimum Height: | 18px
Maximum Width: | unlimited
Maximum Height: | unlimited


.Tiny

CustomBar: Skin Reference

Edit.Tiny

Tiny edit box. Can expect height to be fairly small. Make sure to specify readable font and text color settings! Since edit boxes can be multiline, there is no maximum height that the edit box is expected to look good. However, tiny edit boxes will never be more than 14px tall if they are a single line.

Default Width Range: | min 80px, max 100px
Default Height Range: | min 14px, max 18px
Minimum Width: | 16px
Minimum Height: | unlimited
Maximum Width: | unlimited
Maximum Height: | 20px


.Transparent

CustomBar: Skin Reference

Edit.Transparent

An edit box that must be entirely transparent in any state. No width or height rules exist. Font should match Edit.Tiny. It is recommended that you examine the default WhiteAsh skin for examples.

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.SeparatorH

CustomBar: Skin Reference

Image.SeparatorH

The separator used on horizontal bars. Suggested default width is 5px. Separator prefab adds a default of 4px margin to each side, so a 5px separator would actually separate controls by 13 pixels. Recommended separator width is 2 or 3px.

Default Width Range: | min 1px, max 6px
Default Height Range: | min 1px, max 16px
Minimum Width: | 1px
Minimum Height: | 5px
Maximum Width: | 6px
Maximum Height: | unlimited


.Heading

CustomBar: Skin Reference

Label.Heading

Can be used in containers to label areas. Should be larger than Label.Normal. A bold font is recommended.

Default Width Range: | min 10px, max 60
Default Height Range: | min 1px, max 18px
Minimum Width: | 10px
Minimum Height: | 16px
Maximum Width: | unlimited
Maximum Height: | unlimited


.Monospace

CustomBar: Skin Reference

Label.Monospace

This style of label is generally only used on containers and is expected to be taller than Label.Normal. The monospace label MUST use a monospace font. Courier New at 10pt is recommended.

Default Width Range: | min 10px, max 60
Default Height Range: | min 1px, max 18px
Minimum Width: | 10px
Minimum Height: | 16px
Maximum Width: | unlimited
Maximum Height: | unlimited


.Normal

CustomBar: Skin Reference

Label.Normal

The most frequently used label style. Many prefabs display system stats and and other information inside labels, and this is the default style for most of them. The default font should be small enough to fit comfortably in a 14 pixel high label. Since so many prefabs use Label.Normal, readability needs to be a high priority.

Default Width Range: | min 10px, max 60
Default Height Range: | min 1px, max 18px
Minimum Width: | 10px
Minimum Height: | 14px
Maximum Width: | unlimited
Maximum Height: | unlimited


.SongInfo

CustomBar: Skin Reference

Label.SongInfo

This is used by audio/video prefabs to display current song and other information. This version has to be able to handle a wide variety of sizes, so make sure the font chosen fits (see SampleBar 1 for good example).

Default Width Range: | min 100px, max unlimited
Default Height Range: | min 12px, max 18px
Minimum Width: | 16px
Minimum Height: | 12px
Maximum Width: | unlimited
Maximum Height: | unlimited


.SongInfoStatic

CustomBar: Skin Reference

Label.SongInfoStatic

This is used by audio/video prefabs to display current song and other information. This version is used only be prefabs that follow specified DefaultHeight. The label must still be capable of handling a variety of widths, as DefaultWidth is not necessarily obeyed.

Default Width Range: | min 100px, max unlimited
Default Height Range: | min 12px, max 18px
Minimum Width: | 16px
Minimum Height: | No minimum height.
Maximum Width: | unlimited
Maximum Height: | No maximum height.


.Transparent

CustomBar: Skin Reference

Label.Transparent

A label that must be entirely transparent in any state. No width or height rules exist. Font should match Label.Normal. It is recommended that you examine the default WhiteAsh skin for examples.

Default Width Range: | don't specify DefaultWidth
Default Height Range: | don't specify DefaultHeight
Minimum Width: | No minimum width.
Minimum Height: | No minimum height.
Maximum Width: | No maximum width.
Maximum Height: | No maximum height.


.Vertical

CustomBar: Skin Reference

Slider.Vertical

14px wide slider, must handle any height. For example, see the volume controls that come with Audio.QuickControl prefab.

Default Width Range: | 14px
Default Height Range: | min 12px, max 14px
Minimum Width: | 14px
Minimum Height: | 16px
Maximum Width: | 16px
Maximum Height: | unlimited


Appendix B: Valid Fonts

Different computer systems have different fonts available. In order to minimize the chances of a skin requiring a font that is not present on most people's systems, this list of common Windows fonts has been compiled. A skin that meets the Skin Specification can use only the fonts in this list.

These fonts are listed by Microsoft as being available on releases of Windows 98, Windows ME, Windows 2000, and Windows XP or as an addition by Internet Explorer 4 or higher. Since CustomBar requires Windows 98 or higher and Internet Explorer 4 or higher, these fonts can be assumed to be safe to use. If errors or omissions exist in this list, please contact software@lizardsoft.com

More information on these fonts can be found on Microsoft's typography page.

Arial
Arial Black
Arial Bold
Arial Bold Italic
Arial Italic
Comic Sans MS
Comic Sans MS Bold
Courier New
Courier New Bold
Courier New Italic
Courier New Bold Italic
Georgia
Georgia Bold
Georgia Bold Italic
Georgia Italic
Impact
Lucida Console
Marlett
Symbol
Tahoma
Tahoma Bold
Times New Roman
Times New Roman Bold
Times New Roman Bold Italic
Times New Roman Italic
Trebuchet MS
Trebuchet MS Bold
Trebuchet MS Bold Italic
Trebuchet MS Italic
Verdana
Verdana Bold
Verdana Bold Italic
Verdana Italic
Webdings
Wingdings

The above are all exact typeface names that can be specified directly as spelled in this guide.


CustomBar Prefab Creation Manual

Welcome to the CustomBar prefab creation manual. Learn how to create your own prefabs for CustomBar, just like the ones that come with it! Please send any comments and suggestions about this manual to helpfeedback@custombar.net.

Contents:

1. Getting Started

2. Tutorials

3. Reference


Getting Started

CustomBar prefabs are the "glue" that combines the CustomBar skinnable interface and CustomBar plugins into a neat object that a user can place on the bar through BarCreator. Like most CustomBar data files, including skins, prefabs are written in a custom scripting language known as TDSettings. It looks similiar to an .ini file and consists mostly of a list of settings and their values.

Note that prefabs are not plugins. Plugins are simply libraries of functions that prefabs take advantage of to "get stuff done". CustomBar comes with several built-in plugins that provide a wealth of functionality to prefab creators. Knowing how to create plugins is not necessary for creating prefabs.

Required Knowledge: The CustomBar prefab system was created with the goal of making it as accessible as possible. You only need to know how to use Notepad or similar text editor, and be comfortable with the idea of learning a simple scripting language.

The easiest way to get into prefab development is by reading the tutorials in this help file. You can also play around with the prefabs that come with CustomBar, but be warned that they were created using some advanced features and aren't necessarily a good newbie starting point. The tutorials dampen the learning curve significantly while allowing you to dive straight into creating a custom prefab.

Read This If You Want To Create Plugins: To enhance CustomBar functionality, it is possible to write additions using C++. If you are considering writing plugins, you should learn how to write prefabs first, since you will need this knowledge before you can create a plugin.


CustomBar Prefab Tutorials

Getting started with CustomBar prefabs is easiest by following the tutorials included in this help file. The tutorials will get you up to speed quickly while showing you practical examples. More tutorials will be added in later versions of this help file.

Available Tutorials:

1. Getting Started: Creating a Search Box


Tutorial 1: Creating a Search Box

This step-by-step tutorial will lead you through the process of writing your first CustomBar prefab. We will begin by creating a simple search box, similiar to the Search.Web prefab that comes with CustomBar. By the time you are done this tutorial, you will know how to create an edit box, how to make it do something, and how to make your prefab visible in BarCreator. In later tutorials, we will expand on this example and add more advanced features, such as a window that appears when the box is right-clicked.

How Prefabs Are Organized

All prefabs that are visible to CustomBar must be placed in the Prefabs folder of CustomBar.Each folder inside the Prefabs folder represents a prefab category. Each folder inside a category folder is a prefab. Prefabs can also have one or more styles. For now we won't worry about styles, but it is important to know that they exist. You will notice in this documentation that we will often refer to a prefab name using a format such as Organization.Notepad or SystemInfo.UpTime:Digital. The text before the dot is the prefab's category, the text after is the prefab name. The optional style is indicated using a colon.

Naming Our New Prefab

The first thing a new prefab needs is a category and a name. Whenever possible, you should use one of the already created categories instead of creating your own. However, if you are creating a whole set of prefabs, then it might make sense to group them together in their own new category. Since the prefab we will be creating will be used for searching, we will create it inside the Search category. The name we create for our prefab should be simple but we also want to make it unique enough to avoid name-conflicts with other prefabs.

The prefab we are creating will be used to search Google, or alternatively, your favorite search engine. Let's name it MyWebSearch. Create a folder in the CustomBar\Prefabs\Search\ folder called MyWebSearch. All our prefab files will go in this folder.

Important Note: Prefab names can only consist of letters. Do not use spaces or special characters in prefab names.

The Prefab Information File

Every prefab must have a file called info.tds in its folder. This file tells CustomBar where to find the other prefab files, and specifies general prefab information.

Create a new text file (using a program like Notepad) and save it in the MyWebSearch folder as info.tds. Copy and paste the following text into it:

[INFO]

Name = "MyWebSearch"
Author = "Some Person"

[STYLES]

Default = "code_default.tds"

[STYLESEDIT]

Default = "edit_default.tds"

Congratulations, you have just created a TDSettings, or TDS, file. As you can see, it is just a list of settings. The text in square brackets represents categories. Let's go through each setting in info.tds:

Name: This should be the name of your prefab, and has to match the name of the prefab folder. Remember, no spaces or characters other than letters. Don't worry, a user-friendly name can be specified elsewhere.

Author: The person who created this plugin. Put your name or handle or whatever you like here.

The [STYLES] and [STYLESEDIT] categories tell CustomBar where to find the prefab script(s) and where BarCreator can find information on how to edit the settings for your prefab. In a later tutorial you will learn how you can make various styles of the same prefab. For now we will use the code above to specify that our prefab code is in a file called code_default.tds and that our edit information is in edit_default.tds. You can name the files whatever you like, but we suggest using the code_ and edit_ naming convention.

The Edit Information File

Normally it makes more sense to create the prefab code file first, but in the interest of getting a prefab working as quickly as possible, we will do things backwards. The edit information file (edit_default.tds) tells BarCreator how to display your prefab information, what settings can be edited, and what default values to assign to settings.

[INFO]

DisplayName = "Web Search"
Author = "Some Person"

Description = "A cool search box."

[@SETTINGS]
@IncStart = 1

@template = EditTemplate.DisplayName
@template = EditTemplate.NewRow
@template = EditTemplate.Layout

[DEFAULTSETTINGS]

DisplayName = "Web Search"

XPos = 2
YPos = 0

HorzAlign = "left"
VertAlign = "center"

Width = "100"
Height = "14"

The settings in the [INFO] category provide a way to specify a user-friendly version of the prefab name, as well as a description and author information. BarCreator uses this information when displaying your prefab in the prefab gallery. The [@SETTINGS] category and subsequent @IncStart line are necessary to have the file work correctly. It must go right after the [INFO] category.

The @template lines tell BarCreator that we want to include two predefined settings and that we want to make sure are each on their own line. Predefined settings make it easy to include common prefab settings without having to write a lot of code. It is also possible to create your own custom settings, which will be covered in a later tutorial. The predefined settings we have included are DisplayName, which affects the name of the prefab in the list of prefabs on the current bar. The Layout setting is the second setting we are including, and it is actaully a set of settings that allow the user to control the positioning of our prefab on the bar.

The [DEFAULTSETTINGS] category allows us to specify default settings for our prefab. Since we have not created any custom settings, we need to only specify the defaults for the predefined settings that we have imported. Note that the Layout predefined setting actually created 6 settings, all of which allow the user to control how our prefab appears on the user's bar.

The Prefab Code File

This is it, time to actually have our prefab do something. So far we have an information file and an edit file, but we don't have an actual prefab. For the most part, prefab code files are simply lists of controls and settings that control how the controls behave.

Create a file called code_default.tds, save it in the prefab folder where info.tds and edit_default.tds are. Paste the following into it:

[@SETTINGS]
@IncStart = 1

[@INC]
{Edit}

Gfx = XPos = Prefab.XPos
YPos = Prefab.YPos
Width = Prefab.Width
Height = Prefab.Height
HorzAlign = Prefab.HorzAlign
VertAlign = Prefab.VertAlign
HorzAlignType = "relative"
VertAlignType = "absolute"

Text = ""
ReadOnly = false

ExecProc = "System.OpenURL( 'http://www.google.com/search?q=^String.UrlEncode('^Element.GetText()^')^ ' );"

General Code File Layout
The first two lines must be the first two lines of every prefab code file. After this are one or more [@INC] categories. Each [@INC] specifies a new interface element (or in more advanced situations, a prefab). After the [@INC] line, the type of control is specified. In our case it is {Edit} because we want an edit box. Other possibilities include {Button}, {Label}, {Slider} and more. Following that, a number of settings are specified. While most settings apply to all controls, each control also has special settings of its own. Most settings can be safely omitted. Settings that should be specified always for all controls are Gfx and the variious layout-related settings.

Our prefab has only one control, an edit box. Let's go through each setting that we use:

Gfx: This is the skin element used by the control. In our case we have specified Edit.Tiny, which is the recommended skin element for small edit controls. You can view the skin reference to see a full list of available skin parts.

XPos: Specifies how far away horizontally (in pixels) from the previous control this control will be placed. Note that instead of setting it ourselves, we have specified it as Prefab.XPos. This tells CustomBar to use the value for the XPos setting that the user set in BarCreator. If we had just specified a number, the user setting would be ignored and that number would be used. The exact meaning of XPos depends on the alignment settings set for the control. Read the prefab reference for more information on this setting.

YPos: Specifies the vertical offset for the control. Since we have instructed the control to be centered vertically, this value will cause the control to be shifted down or, if it's negative, to be shifted up. Note that instead of setting it ourselves, we have specified it as Prefab.YPos. This tells CustomBar to use the value for the YPos setting that the user set in BarCreator. If we had just specified a number, the user setting would be ignored and that number would be used. The exact meaning of XPos depends on the alignment settings set for the control. Read the prefab reference for more information on this setting.

Width: This is a value in pixels or percentage points that specifies the width of the edit control. For the purposes of this tutorial, we are allowing the user to set the width and assuming it is in pixels.

Height: This is a value in pixels or percentage points that specifies the height of the edit control. For the purposes of this tutorial, we are allowing the user to set the height and assuming it is in pixels.

HorzAlignType: Specifies the type of alignment used for horizontal positioning of the control. We are assuming that our prefab is being placed on a horizontal bar and that we want the control to appear after the previous control on the bar, so we have set alignment to "relative". If we had set it to "absolute", the control would have been positioned horizontally exactly where XPos specifies.

VertAlignType: Specifies the type of alignment used for vertical positionining of the control. We are assuming that our prefab is being placed on a horizontal bar, so we the vertical position of the control to be specifiable exactly by YPos. Therefore we set the alignment to "absolute". Had we set it to "relative", CustomBar would have attempted to place it vertically after the last control that had VertAlignType set as "relative". This would not make any sense on a horizontal bar, but will be useful once you start creating container windows.

HorzAlign: Determines how the control is aligned horizontal. We are letting the user choose this through BarCreator. Possible values are "left", "center", and "right". The effect of each setting should be fairly self-explanatory.

VertAlign: Determines how the control is aligned vertically. We are letting the user choose this through BarCreator. Possible values are "top", "center", and "bottom". The effect of each setting should be fairly self-explanatory. Most controls placed on a horizontal bar should be centered vertically as this looks the neatest.

Text: This is the text that appears by default in the edit box. We have left it blank for now. In a later tutorial, we will take advantage of this setting to create a label for the search box when it is not being typed into.

ReadOnly: This value can be set to true to prevent a user from being able to type into the edit box. Note the lack of quotations around the word false. ReadOnly uses a special TDS setting type called boolean, which allows a setting to be set to true or false. Do not put quotation marks around this value.

ExecProc: This is the most important setting, because it actually gives our edit box instructions on what to do. The action specified in ExecProc is executed when the user presses the enter key after typing into the box. There are quite a few different types of Proc settings, each getting executed when a different action occurs. More on ExecProc in a sec.

Note that the edit box has more settings than we have used. You will need to look through the prefab reference for a comprehensive list and more detailed explanations. The prefab reference will also provide you the information that you need to make use of controls other than the edit box.

Testing the Prefab

Before we move on to a more detailed explanation of how the search box functions, let's verify that our finished plugin works. If you followed the instructions in this tutorial carefully, you should have a folder in the CustomBar\Prefabs\Search\ folder called MyWebSearch. Inside CustomBar\Prefabs\Search\MyWebSearch you should have three files titled info.tds, edit_default.tds, and code_default.tds These files should have the appropriate code pasted into them. If you have done all this, you should be able to open up BarCreator and see your prefab in the Prefab Gallery under the Search category. Try adding it to your bar, and selecting Launch Bar in BarCreator. Your bar should load with an edit box on it. If you type something into the edit box and press Enter, your browser should open and go to the Google search page with the search results for the text that you entered (assuming that you have an internet connection).

If this doesn't work, go back and check that you followed this tutorial carefully.If you edited the files in any way, such as changing the author, then note that some characters in TDS files have special meanings. For example, if you used a \ or " character in your author name, you need to put a \ character before it.

Understanding Procs and Scripting

The slightly strange statement in the ExecProc setting is the key to the functionality of our prefab. Procs are instructions for CustomBar to execute when an event happens, such as the user clicking on a control, the mouse hovering over a control, a timer going off, or the control being created, just to name a few. The prefab reference has a full list of the various Proc settings, and when they get executed for various controls. ExecProc is the most common type of Proc, and has slightly different meanings depending on the control it is used for. For a button, the ExecProc is executed when the user clicks it. For an edit box, it is executed when the user presses enter. It is basically the "default action" Proc.

Procs consist of their mini-language. Currently this language is simply a list of calls to plugin functions. Plugin functions are what actually cause something to happen. CustomBar provides a number of built-in plugins, each with quite a few functions. Users with C++ knowledge can also create new plugins, thus allowing CustomBar to do pretty much anything. Before we analyze the ExecProc we used for the edit box, let's examine a simpler one:

ExecProc = "AudioPlayer.Play();"

This is how an ExecProc for a play button might look. It calls one plugin function called AudioPlayer.Play(). The text before the dot indicates the name of the plugin, the text after the dot indicates the name of the function we are calling. If we were to replace the ExecProc we specified for our search box with this one, CustomBar would tell Winamp to play the current track everytime the user typed something into the box and pressed the Enter key.

Now look back at the ExecProc for our search box:

ExecProc = "System.OpenURL( 'http://www.google.com/search?q=^String.UrlEncode('^Element.GetText()^')^ ' );"

There are two main differences between this ExecProc and the simple AudioPlayer example. This time the proc is passing values to plugin functions, and more than one plugin function is being called. This is also a fairly extreme example in terms of complexity. Most procs are much simpler. Before attempting to understand the mess, let's break this proc into a simpler one:

ExecProc = "System.OpenURL( 'http://www.custombar.net' );"

Pretend the ExecProc is the one above. The System.OpenURL plugin function opens the browser to the address specified in the first paramter. Note the single quotes around the http://www.custombar.net address. Everything inside those quotes is passed as the parameter. In the example above, pressing enter after typing into the edit box will launch the CustomBar site. Not exactly the desired behavior, but we are getting somewhere.

Now examine this proc:

ExecProc = "System.OpenURL( 'http://www.google.com/search?q=^Element.GetText()^ ' );"

It was simple enough to make the browser launch a hard-coded address, but now we need to get the information from the edit box. The above proc will launch google search with the contents of the edit box as the query string. Note that the Element.GetText() call is surrounded by ^ characters. This special syntax allows you to insert function calls inside of parameters to other function calls. Since Element.GetText() returns the text in the edit box, the paramter that gets passed to System.OpenURL ends up having the fully constructed address.

All is not perfect yet. Let's examine the final proper version:

ExecProc = "System.OpenURL( 'http://www.google.com/search?q=^String.UrlEncode('^Element.GetText()^')^ ' );"

This example introduces the final version of the proc. This time we are complicating things further by calling String.UrlEncode() to process the result from Element.GetText(). String.UrlEncode converts special characters such as spaces to their appropriate entities in urls. This allows you to type a query like "the cat" without it getting mangled. If things look confusing, read this section again. The building blocks of calls to procs are actually quite simple.

What to do Next

You are encouraged to experiment and make your own changes to this prefab. For a list of plugin functions that come with CustomBar, see the Standard Plugins reference. Over time more tutorials will be added, giving step-by-step instructions for more advanced aspects of prefab creation. In the meantime, your absolute best sources for learning more about creating prefabs are the existing CustomBar prefabs. Feel free to look through all their code and try to understand how they work.

You should also visit the CustomBar Forums, where a forum dedicated to prefab discussion is located.


Prefab Reference

Welcome to the CustomBar prefab reference. Currently the reference includes documentation of every single standard CustomBar plugin function. Additional references on things like control properties will be included in future versions of this help file.

Standard Plugin Reference


Standard Plugin Reference

CustomBar comes with a wealth of standard plugins, allowing a tremendous amount of different prefabs to be created without ever having to write a plugin. In fact not even the prefabs that come with CustomBar use all the standard plugin functions. This leaves plenty of room for third-party innovation.

This detailed reference documents all the standard plugin functions. It is invaluable to have on hand when creating prefabs.

Standard Plugins

AudioPlayer

The AudioPlayer plugin provides functionality for controlling the user's audio player software. Features include the ability to automatically detect the software, functions for controlling playback, and ability to retrieve information from the player. Historically, this is the first plugin that was written for CustomBar.

Element

The Element plugin provides control over the interface elements on a bar. This is a special plugin with additional extensions built into CustomBar to support easy referencing of elements.

String

The String plugin allows some common text manipulations to be done, such as URL encoding.

System

Provides functionality for performing general system tasks. It is primarily used to make something happen, such as launching a program or changing the system volume.

SystemInfo

The SystemInfo plugin is used for retrieving many standard pieces of information about system status, such as uptime, memory and disk usage.


AudioPlayer Plugin

The AudioPlayer plugin provides functionality for controlling the user's audio player software. Features include the ability to automatically detect the software, functions for controlling playback, and ability to retrieve information from the player. Historically, this is the first plugin that was written for CustomBar.

Audio player support is currently limited to Winamp 2 and Winamp 5. At this time, Lizardsoft has no plans to add support for other players. However, the AudioPlayer plugin has been written in a way that makes adding support for more players easy. If you are interested in adding support for your favorite audio or media player, please visit the CustomBar Forums. You will find a forum there dedicated to plugins and featuring information on how to add support for new players. In the spirit of allowing the CustomBar community to have a hand in the future of CustomBar, we are willing to include well-written and stable additions in future official releases of CustomBar.


AudioPlayer.CurrentSong

CustomBar: Plugin Reference

AudioPlayer.CurrentSong

Gets the currently playing song.

AudioPlayer.CurrentSong( string DefaultText = "No song loaded" )

Parameters

DefaultText

Text to return if no song is loaded.

Return Value (string)

Returns song title or DefaultText if no song is loaded.


AudioPlayer.ElapsedTime

AudioPlayer.ElapsedTime

Gets the time position of the current track. Format of return value may be optionally specifiable in a future release.

AudioPlayer.ElapsedTime( )

Parameters

This function takes no parameters.

Return Value (string)

Returns the position of the current track in the format hours:minutes:seconds.


AudioPlayer.GetBitrate

AudioPlayer.GetBitrate

Obtains the bit rate of the currently playing track. Returns 0 if no track is loaded.

AudioPlayer.GetBitrate( )

Parameters

This function takes no parameters.

Return Value (integer)

Returns the bitrate. Units are dependent on audio player.


AudioPlayer.GetVolume

AudioPlayer.GetVolume

Returns current player volume.

AudioPlayer.GetVolume( )

Parameters

This function takes no parameters.

Return Value (integer)

Player volume as a number between 0 and 255.


AudioPlayer.MuteOff

AudioPlayer.MuteOff

Unmutes sound. Note that currently this applies to the entire system wave volume. This may change to apply only to the player in a future release.

AudioPlayer.MuteOff( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.MuteOn

AudioPlayer.MuteOn

Mutes sound. Note that currently this applies to the entire system wave volume. This may change to apply only to the player in a future release.

AudioPlayer.MuteOn( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.NextTrack

AudioPlayer.NextTrack

Equivalent of pressing next track button on the audio player.

AudioPlayer.NextTrack( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.OpenDirDlg

AudioPlayer.OpenDirDlg

Displays the "Play Folder" dialog of the audio player.

AudioPlayer.OpenDirDlg( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.OpenFileDlg

AudioPlayer.OpenFileDlg

Displays the "Open File" dialog of the audio player.

AudioPlayer.OpenFileDlg( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.OpenFileInfoDlg

AudioPlayer.OpenFileInfoDlg

Displays the file information dialog of the audio player. Won't necessarily be displayed if no song is loaded.

AudioPlayer.OpenFileInfoDlg( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.OpenMainWindow

AudioPlayer.OpenMainWindow

Displays the audio player.

AudioPlayer.OpenMainWindow( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.OpenURLDlg

AudioPlayer.OpenURLDlg

Displays the "Open URL" dialog of the audio player.

AudioPlayer.OpenURLDlg( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.Play

AudioPlayer.Play

Equivalent of hitting play on the audio player.

AudioPlayer.Play( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.PrevTrack

AudioPlayer.PrevTrack

Equivalent of pressing previous track button on the audio player.

AudioPlayer.PrevTrack( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.RemainingTime

AudioPlayer.RemainingTime

Gets time remaining in the current track. Format of return value may be optionally specifiable in a future release.

AudioPlayer.RemainingTime( )

Parameters

This function takes no parameters.

Return Value (string)

Returns the remaining time of the current track in the format hours:minutes:seconds.


AudioPlayer.SetVolume

AudioPlayer.SetVolume

Sets the volume of the player. Note that older versions of Winamp 2 did not have their own volume control and used the system wave volume instead. In the case of older Winamp 2, the system wave volume will be set instead.

AudioPlayer.SetVolume( NewVolume )

Parameters

NewVolume

Volume to set player to. Must be a number between 0 and 255 inclusively.

Return Value (string)

Does not have a valid return value.


AudioPlayer.Stop

AudioPlayer.Stop

Equivalent of hitting stop on the audio player.

AudioPlayer.Stop( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleEqualizer

AudioPlayer.ToggleEqualizer

Displays or hides the equalizer window.

AudioPlayer.ToggleEqualizer( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleMediaLibrary

AudioPlayer.ToggleMediaLibrary

Displays or hides the media library.

AudioPlayer.ToggleMediaLibrary( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleMute

AudioPlayer.ToggleMute

Toggles mute. Note that currently this applies to the entire system wave volume. This may change to apply only to the player in a future release.

AudioPlayer.ToggleMute( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.TogglePause

AudioPlayer.TogglePause

Pauses current track if playing, unpauses if paused.

AudioPlayer.TogglePause( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.TogglePlayList

AudioPlayer.TogglePlayList

Displays or hides the play list window.

AudioPlayer.TogglePlayList( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleRepeat

AudioPlayer.ToggleRepeat

Toggles repeat/loop mode on player.

AudioPlayer.ToggleRepeat( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleShuffle

AudioPlayer.ToggleShuffle

Toggles shuffle mode on player.

AudioPlayer.ToggleShuffle( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.ToggleVideo

AudioPlayer.ToggleVideo

Displays or hides the video window.

AudioPlayer.ToggleVideo( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


AudioPlayer.TrackLength

AudioPlayer.TrackLength

Gets the length of the current track. Format of return value may be optionally specifiable in a future release.

AudioPlayer.TrackLength( )

Parameters

This function takes no parameters.

Return Value (string)

Returns the length of the current track in the format hours:minutes:seconds.


Element Plugin

The Element plugin provides control over the interface elements on a bar. This is a special plugin with additional extensions built into CustomBar to support easy referencing of elements.

Every function in the Element plugin can be called in two different ways:

No Element Name: If you call an Element function using the normal plugin function call syntax, then CustomBar assumes that you are referring to the current element. For example, if you have defined an edit box and set the ExecProc to:

ExecProc = "Element.SetText('Hello');"

Every time the user pressed enter while editing the edit box (assuming single line edit box), the edit box's text would be changed to "Hello".

Element Name: The Element plugin allows you to specify which interface element you wish to manipulate by specifying the element name in square brackets right after the plugin name:

ShowProc = "Element[->RunURL].SetText('Hello'); "

In the above example, if the ShowProc belongs to a container, and it has an edit box child named "RunURL", then RunURL's text would be set to hello. Note the '->' used to indicate that we are looking for a child of the container. Had that been omitted, CustomBar would have looked for a global element named "RunURL". There are also other ways to specify element names relative to each other. Please consult the documentation on prefab creation to learn more.


Element.Display

Element.Display

Displays an element. Capable of correctly displaying all types of elements. Fails silently if specified element cannot be displayed. The element is displayed relative to the element displaying it. This is very important when displaying containers and menus, since CustomBar will attempt to display these close to the element that is requesting them to be displayed.

Element.Display( string Element, string Alignment )

Parameters

Element

Name of the element to display. See documentation on the CustomBar namespace for special characters that can be used.

Alignment

Preferred alignment for the container or menu relative to the element displaying it. Valid values are 'LEFT', 'CENTER', and 'RIGHT'.

Return Value

No return value.


Element.DisplayAppMenu

Element.DisplayAppMenu

Displays the CustomBar application menu.

Element.DisplayAppMenu( string Alignment )

Parameters

Alignment

Preferred alignment for the menu relative to the element displaying it. Valid values are 'LEFT', 'CENTER', and 'RIGHT'.

Return Value

No return value.


Element.GetText

Element.GetText

Gets the control's actual text.

Element.GetText( )

Parameters

This function takes no parameters.

Return Value (string)

Returns the control's text.


Element.GetTimerProc

Element.GetTimerProc

Returns the element's "TimerProc". This is the proc that gets called whenever the element's timer goes off.

Element.GetTimerProc( )

Parameters

This function takes no parameters.

Return Value (string)

Returns the TimerProc script for the element.


Element.GetValue

Element.GetValue

Gets the element's value. This is currently used for controls with integer values (ie. sliders). For elements that store text information use Element.GetText.

Element.GetValue( )

Parameters

This function takes no parameters.

Return Value (integer)

Returns the element's value.


Element.LoadFromFile

Element.LoadFromFile

For text controls (eg. edit boxes) this loads a text file into the control. In future releases of CustomBar, it will also be possible to load graphical files into graphical controls with this file.

Element.LoadFromFile( string File )

Parameters

File

Full path of the file to load.

Return Value

No return value.


Element.SaveToFile

Element.SaveToFile

For text controls, saves the control's contents to a text file.

Element.SaveToFile( string File )

Parameters

File

Full path of the file to save to.

Return Value

No return value.


Element.SetText

Element.SetText

Sets the control's actual text. Note that this is different from setting the control's TextProc, which updates the control text every TimerRate milliseconds with its contents. This function is mostly used to easily set text in controls such as edit boxes, and for setting large amounts of text. For more information on the differences between SetText and SetTextProc, see the Scripter's Control Documentation.

Element.SetText( string NewText )

Parameters

NewText

New text to replace control text with.

Return Value

No return value.


Element.SetTextAlign

Element.SetTextAlign

Sets the horizontal alignment of text in an element.

Element.SetTextAlign( string Alignment )

Parameters

Alignment

New text alignment. Valid values are 'LEFT', 'CENTER', and 'RIGHT'.

Return Value

No return value.


Element.SetTimerProc

Element.SetTimerProc

Sets the "TimerProc" script of an element.

Element.SetTimerProc( string Script )

Parameters

Script

New script for element's TimerProc.

Return Value

No return value.


Element.SetValue

Element.SetValue

Sets the value for a control whose values are stored numerically (eg. sliders).

Element.SetValue( integer NewValue )

Parameters

NewValue

New value to set for the control.

Return Value

No return value.


String Plugin

The String plugin allows some common text manipulations to be done, such as URL encoding. In its current state it is still largely under construction and will be further developed in future versions of CustomBar.


String.ToLower

String.ToLower

Converts a string to lowercase.

String.ToLower( string Str )

Parameters

Str

String to convert to lowercase

Return Value (string)

Returns the converted string.


String.ToUpper

String.ToUpper

Converts a string to uppercase.

String.ToUpper( string Str )

Parameters

Str

String to convert to uppercase

Return Value (string)

Returns the converted string.


String.UrlEncode

String.UrlEncode

Encodes a url so that special characters don't cause problems. For example, space gets converted to %20.

String.UrlEncode( string Url )

Parameters

Url

Url to convert.

Return Value (string)

Returns the encoded url.


System Plugin

The System plugin provides functionality for performing general system tasks. It is primarily used to make something happen, such as launching a program or changing the system volume. A separate plugin, SystemInfo, is used for retrieving information about the system.


System.CascadeAll

System.CascadeAll

Cascades all windows on desktop.

System.CascadeAll( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.CopyToClipboard

System.CopyToClipboard

Copies a string or a file's contents to the clipboard.

System.CopyToClipboard( string Source, string Operation = "copy", string SourceType = "string" )

Parameters

Source

A string or file to copy to the clipboard

Operation

Set to "copy" to copy to the clipboard, set to "copypaste" to copy to clipboard and then paste into last (not current) foreground window.

SourceType

"string" if Source is the string to copy, "file" if Source is a path to a file whose contents are to be copied.

Return Value (string)

Does not have a valid return value.


System.EjectPC

System.EjectPC

Ejects the computer from docking station if supported.

System.EjectPC( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.EmptyRecycleBin

System.EmptyRecycleBin

Empties the recycle bin.

System.EmptyRecycleBin( string Confirm = "", string Sound = "", string Progress = "", string Path = "" )

Parameters

Confirm

"1" to have the user prompted to confirm they want to empty reycle bin, "NOCONFIRMATION" to suppress the dialog and assume yes.

Sound

Set to "NOSOUND" to suppress the sound that is played after reycle bin is emptied.

Progress

"1" to show recycle bin emptying progress window, "NOPROGRESS" to suppress the window.

Path

Specify only if you want to limit the recyle bin emptying to a specific drive or path.

Return Value (string)

Does not have a valid return value.


System.Execute

System.Execute

Executes a given file with given shell verb. Internally calls the Win32 API function ShellExecute(). Can be used to open applications, open files in their associated programs, launch search windows, explore folders, and more.

System.Execute( string ShellVerb, string File, string Parameters = "", string WorkingDir = "", string ShowType = "normal" )

Parameters

ShellVerb

Shell verb to use on folder. Typically "open" or "explore" are used. Other valid verbs include "edit", "find", and "print". Depending on the file type, more verbs may be available.

File

File to perform the specified shell verb on.

Parameters

Command line paramaters to pass.

WorkingDir

"Working directory" set for launched application. Not generally needed.

ShowType

Sets the prefered window state of the application launched to view the file. Can be "NORMAL", "MAXIMIZED", or "MINIMIZED".

Return Value (string)

Does not have a valid return value.


System.GetVolume

System.GetVolume

Returns the system volume as a value between 0 and 255.

System.GetVolume( )

Parameters

This function takes no parameters.

Return Value (integer)

Volume between 0 and 255 where 0 is lowest volume and 255 is highest.


System.GetWaveVolume

System.GetWaveVolume

Returns the wave volume as a value between 0 and 255.

System.GetWaveVolume( )

Parameters

This function takes no parameters.

Return Value (integer)

Volume between 0 and 255 where 0 is lowest volume and 255 is highest.


index

System.MessageBox

Displays a simple message box.

System.MessageBox( string Message, string Caption = "", string Buttons = OK )

Parameters

Message

Message to display.

Caption

Titlebar text on message box.

Buttons

Buttons to display on MessageBox. Valid values include: "OK", "YESNO", "YESNOCANCEL", "OKCANCEL", "RETRYCANCEL", "ABORTRETRYIGNORE".

Return Value (string)

Returns the name of the button that was pressed (all capitals).


System.MinimizeAll

System.MinimizeAll

Minimizes all windows.

System.MinimizeAll( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.MuteOff

System.MuteOff

Unmutes system sound.

System.MuteOff( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.MuteOn

System.MuteOn

Mutes system sound.

System.MuteOn( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.OpenBrowser

System.OpenBrowser

Opens new instance of default browser.

System.OpenBrowser( string ShowType = "normal" )

Parameters

ShowType

Sets the prefered window state of the launched browser. Can be "NORMAL", "MAXIMIZED", or "MINIMIZED".

Return Value (string)

Does not have a valid return value.


System.ShowFileRun

System.ShowFileRun

Displays the Windows Run box that is normally available through Start->Run.

System.ShowFileRun( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.OpenFolder

System.OpenFolder

Preferred way to open a folder window. Performs some special operations that help make sure that the folder actually gets opened.

System.OpenFolder( string ShellVerb, string Folder, string ShowType = "normal" )

Parameters

ShellVerb

Shell verb to use on folder. Typically "open" or "explore" are used. Other valid verbs include "edit", "find" and "print". Depending on the file type, more verbs may be available.

Folder

Folder to perform the specified shell verb on.

ShowType

Sets the prefered window state of the opened folder window. Can be "NORMAL", "MAXIMIZED", or "MINIMIZED".

Return Value (string)

Does not have a valid return value.


System.OpenSpecialFolder

System.OpenSpecialFolder

Opens a special system folder, such as Favorites or My Documents.

System.OpenSpecialFolder( integer Folder, string ShellVerb = "open", string ShowType = "normal" )

Parameters

Folder

Special folder to display. See CSIDL constants in {CustomBar}\Common\system.tds for possible valid values. Not all CSIDL values will work with all shell verbs.

ShellVerb

Shell verb to use on folder. Typically "open" or "explore" are used.

ShowType

Sets the prefered window state of the application launched to view the file. Can be "NORMAL", "MAXIMIZED", or "MINIMIZED".

Return Value (string)

Does not have a valid return value.


System.OpenURL

System.OpenURL

Opens a url for viewing in the default browser.

System.OpenURL( string Site, string OpenType = "normal", string ShowType = "normal" )

Parameters

Site

Internet location to open. eg. "http://www.custombar.net". Protocols such as ftp:// may work as well.

OpenType

Specifies prefered way of launching browser. "NORMAL" suggests using default browser behavior, "NEWWIN" suggests that a new browser window be opened.

ShowType

Sets the prefered window state of the launched browser. Can be "NORMAL", "MAXIMIZED", or "MINIMIZED".

Return Value (string)

Does not have a valid return value.


System.SetDesktopColor

System.SetDesktopColor

Changes the desktop background color for the current user.

System.SetDesktopColor( string Color )

Parameters

Color

The new color to set desktop to. Can be any standard color format recognized by CustomBar, such as "#FFAAFF". See appropriate section of documentation for more on valid color formats.

Return Value (string)

Does not have a valid return value.


System.SetVolume

System.SetVolume

Sets the system volume.

System.SetVolume( integer Volume )

Parameters

Volume

New system volume. 0 is lowest possible, 255 is highest.

Return Value (string)

Does not have a valid return value.


System.SetWallpaper

System.SetWallpaper

Changes the desktop wallpaper on the system for the current user.

System.SetWallpaper( string File )

Parameters

File

Image file to set wallpaper to. Bitmap files are recommended but systems with ActiveDesktop should accept other formats.

Return Value (string)

Does not have a valid return value.


System.SetWallpaperStyle

System.SetWallpaperStyle

Determines how the desktop wallpaper is drawn. Windows allows you to center it, tile it, or stretch it.

System.SetWallpaperStyle( string Style )

Parameters

Style

Set to one of the following values: "CENTER", "TILE", or "STRETCH".

Return Value (string)

Does not have a valid return value.


System.SetWaveVolume

System.SetWaveVolume

Sets the wave volume.

System.SetWaveVolume( integer Volume )

Parameters

Volume

New wave volume. 0 is lowest possible, 255 is highest.

Return Value (string)

Does not have a valid return value.


System.ShowFindComputer

System.ShowFindComputer

Launches the Windows "Find Computer" application.

System.ShowFindComputer( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.ShowFindFiles

System.ShowFindFiles

Launches the Windows search application.

System.ShowFindFiles( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.ShowSetDateTime

System.ShowSetDateTime

Shows the Windows set time dialog that is normally displayed when you double-click the system clock on the taskbar.

System.ShowSetDateTime( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.ShowShutdown

System.ShowShutdown

Shows the Windows Shutdown dialog that is normally presented to the user by selecting Start->Shutdown.

System.ShowShutdown( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.ShowTrayProperties

System.ShowTrayProperties

Shows taskbar and start menu properties.

System.ShowTrayProperties( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.Suspend

System.Suspend

Suspends the computer if supported.

System.Suspend( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.TileAllHorizontally

System.TileAllHorizontally

Tiles all windows on desktop horizontally.

System.TileAllHorizontally( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.TileAllVertically

System.TileAllVertically

Tiles all windows on desktop vertically.

System.TileAllVertically( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.ToggleMute

System.ToggleMute

Mutes system sound if not muted, unmutes it if already muted.

System.ToggleMute( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


System.UndoMinimizeAll

System.UndoMinimizeAll

Reverses effect of a previous call to System.MinimizeAll().

System.UndoMinimizeAll( )

Parameters

This function takes no parameters.

Return Value (string)

Does not have a valid return value.


SystemInfo Plugin

The SystemInfo plugin is used for retrieving many standard pieces of information about system status, such as uptime, memory and disk usage. Some of the functions are only available on Windows 2000 and higher, so read the function reference carefully if you are attempting to be compatible with Windows 98/ME.


SystemInfo.ComputerName

SystemInfo.ComputerName

Obtains the NetBIOS name of the local computer.

SystemInfo.ComputerName( )

Parameters

This function takes no parameters.

Return Value (string)

Returns computer name.


SystemInfo.DiskFreeSpace

SystemInfo.DiskFreeSpace

Obtains the amount of space left on a given drive.

SystemInfo.DiskFreeSpace( string Drive, string Unit, integer Precision )

Parameters

Drive

Drive (or path) to retrieve free space for.

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes
% - Percent.

Precision

Amount of numbers following decimal point to retrieve.

Return Value (string)

Free space on drive in requested unit and precision.


SystemInfo.DownloadRate

SystemInfo.DownloadRate

Measures the download rate for specified network interface. Does not measure traffic that doesn't go through a network connection (ie. won't measure dial-up).

SystemInfo.DownloadRate( string Unit, integer Precision = 0, string Machine = "", string NetworkInterface = "" )

Parameters

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes

Precision

Amount of numbers following decimal point to retrieve.

Machine

Name of machine to query. If not specified, local machine is automatically detected.

NetworkInterface

Network interface to query. This is an advanced value that should generally not be specified, but can be if you wish to query a particular network interface. To find valid values, you need to look for them on your machine's performance counters. Advanced users only.

Return Value (string)

Download rate in requested unit and precision. Can return "0" if network interface not found or this is not an NT-based system.


SystemInfo.FreeMem

SystemInfo.FreeMem

Obtains the amount of free memory available to the system.

SystemInfo.FreeMem( string Unit )

Parameters

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes
% - Percent.

Return Value (integer)

Free memory, in Unit units.


SystemInfo.LocalTime

SystemInfo.LocalTime

Obtains the local computer time.

SystemInfo.LocalTime( string Format )

Parameters

Format

Time string. Can consist of any character, plus the following special values:

%h - hour in 24 hour format
%H - hour in 12 hour format
%m - minute
%s - second
%p - lowercase am or pm
%P - uppercase AM or PM

Example of valid format string: "%h:%m:%s %p"

Return Value (string)

Formatted system time.


SystemInfo.ProcessCount

SystemInfo.ProcessCount

Returns the total amount of processes being run by the system.

SystemInfo.ProcessCount( string Machine = "" )

Parameters

Machine

Name of machine to query. If not specified, local machine is automatically detected.

Return Value (integer)

Total number of processes running on the system, or 0 if not supported or machine not found.


SystemInfo.ProcessorTime

SystemInfo.ProcessorTime

Returns percent of CPU processing capacity that the processor is currently operating at.

SystemInfo.ProcessorTime( string Machine = "" )

Parameters

Machine

Name of machine to query. If not specified, local machine is automatically detected.

Return Value (integer)

Processor workload as a value between 0 and 100, inclusive. Always returns 0 on none-NT systems.


SystemInfo.ThreadCount

SystemInfo.ThreadCount

Returns the total amount of threads being run by the system.

SystemInfo.ThreadCount( string Machine = "" )

Parameters

Machine

Name of machine to query. If not specified, local machine is automatically detected.

Return Value (integer)

Total number of threads running on the system, or 0 if not supported or machine not found.


SystemInfo.TotalMem

SystemInfo.TotalMem

Obtains the amount of physical memory present on the system.

SystemInfo.TotalMem( string Unit )

Parameters

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes
% - Percent.

Return Value (integer)

Physical memory size in Unit units.


SystemInfo.UploadRate

SystemInfo.UploadRate

Measures the upload rate for specified network interface. Does not measure traffic that doesn't go through a network connection (ie. won't measure dial-up).

SystemInfo.UploadRate( string Unit, integer Precision = 0, string Machine = "", string NetworkInterface = "" )

Parameters

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes

Precision

Amount of numbers following decimal point to retrieve.

Machine

Name of machine to query. If not specified, local machine is automatically detected.

NetworkInterface

Network interface to query. This is an advanced value that should generally not be specified, but can be if you wish to query a particular network interface. To find valid values, you need to look for them on your machine's performance counters. Advanced users only.

Return Value (string)

Upload rate in requested unit and precision. Can return "0" if network interface not found or this is not an NT-based system.


SystemInfo.UpTime

SystemInfo.UpTime

Returns the amount of time that has passed since the operating system started.

SystemInfo.UpTime( string Format )

Parameters

Format

Time string. Can consist of any character, plus the following special values:

%d - days (remainder)
%h - hours (remainder)
%m - minutes (remainder)
%s - seconds (remainder)
%D - days (absolute)
%H - hours (absolute)
%M - minutes (absolute)
%S - seconds (absolute)

Examples of valid format strings: "%h:%m:%s", "System up for %D day(s)"

Return Value (string)

Formatted up time.


SystemInfo.UsedMem

SystemInfo.UsedMem

Obtains the amount of memory currently in use by the system. Note that this measures the amount of virtual memory in use, which is the most relevant memory use figure. Due to how Windows handles memory, it may not match the physical RAM in use. It can also exceed the amount of physical RAM on your system. This is not a bug, it just means information is being swapped out and you should invest in more RAM.

SystemInfo.UsedMem( string Unit )

Parameters

Unit

Unit to return information in. Can be one of the following:

B - Bytes
KB - Kilobytes
MB - Megabytes
GB - Gigabytes
% - Percent.

Return Value (integer)

Memory being used in Unit units.


CustomBar Plugin SDK

CustomBar Plugin SDK

Welcome to the CustomBar plugin SDK. Use this to get started with developing plugins for CustomBar. Includes tutorials and source code. Please send any comments and suggestions about this manual to helpfeedback@custombar.net.

Contents:

1. Getting Started

2. Tutorials

3. Sample Plugin Source


Getting Started

The CustomBar plugin SDK allows you to write your own custom additions to CustomBar. These "plugins" come in the form of Windows DLL files and are the most advanced method of extending CustomBar. Writing a plugin requires C programming knowledge and access to a C++ compiler that can generate standard Windows DLL files. The plugin SDK uses a feature of C++ to handle function parameters, however C++ knowledge is not required to write a plugin, just a C++ compiler.

To begin writing plugins, you need the plugin SDK. Although a copy of it comes with your program installation, the CustomBar website likely has an updated version. To use the SDK, you need to place all header (.h) files that come with it into a folder that your programs can include them from, or you need to add the SDK folder to your compiler's list of folders to search for include files. Every plugin you create will have to link to CBPluginLib.lib and DataLib.lib, which are also found in the SDK folder. The plugin creation tutorial covers this information in greater detail.

Required Knowledge: Knowledge of C or C++ is required, along with access to a C++ compiler capable of generating Win32 DLL files. It is also strongly recommended that you learn how to create CustomBar prefabs first, since you will need this knowledge to test your plugin(s).


CustomBar Plugin Tutorials

The CustomBar plugin tutorials will help you get started with CustomBar plugin development. Be sure to also examine the source code of the standard plugins, which is included as part of CustomBar. This section will be updated with more tutorials in future versions of this help file.

Available Tutorials:

1. Basic Tutorial


Tutorial

This step-by-step tutorial will lead you through the process of writing a CustomBar plugin from start to finish. If you have not already done so, you should read the Getting Started section first and have the latest version of the Plugin SDK installed on your system. This tutorial goes through the steps slowly and limits itself to action steps for clarity. For full information on how the plugin system works and all the functionality provided through it, you will need to read the relevant sections of the Plugin SDK documentation.

This tutorial attempts to be generic enough to be used for any C++ compiler, however special notes are provided for Visual Studio .NET users. If you are using another compiler, you will need to consult your compiler documentation for compiler-specific tasks. The full sample plugin that is created using this tutorial is located in the SDK\Samples\Tutorial folder of the SDK.

Creating the Plugin Project

Start by creating a new Win32 DLL project. The DLL will need to export symbols, which may require setting an additional option. The functions that the plugin exports will need to use the C linkage convention (extern "C"). This will be discussed more in a bit.

Visual Studio .NET users: you can do this by selecting the Create New Project option and specifying Win32 Application as the project type. Under Application Settings, set the Application type as DLL and check the Export Symbols box.

Linking with the Plugin SDK

In order to compile, your plugin needs to link to two .lib files that come with the Plugin SDK.These files are DataLib.lib and CBPluginLib.lib. You must also #include the file CBPluginLib.h. That's all there is to it!

Visual Studio .NET users: you can complete this step by selecting the Create New Project option and specifying Win32 Application as the project type. Under Application Settings, set the Application type as DLL and check the Export Symbols box.

Creating the Required Functions

Every CustomBar plugin must provide at least three functions. These functions are Initialize(), Deinitialize(), and GetPluginInfo(). The first two get called when the plugin is loaded and unload respectively, and are there for your convienence. They may do nothing, however they must return 1. GetPluginInfo() provides CustomBar with important information about your plugin. Every function that needs to be exported as a DLL must use C linkage. To accomplish this with your C++ compiler, surround the declaration of your plugin functions in an extern "C" {} block. The following is an example of how a properly created plugin will look at this point. #include statements, function declarations, and DllMain are omitted for clarity. See the sample source code for the complete file. Don't worry about the contents of GetPluginInfo(), it will be explained momentarily.

PLUGIN_FUNC FuncInfo[2];

int Initialize()
{
return 1;
}

int Deinitialize()
{
return 1;
}

int GetPluginInfo( PLUGIN_INFO *Info )
{
Info->Name       = "My First Plugin";
Info->ObjectName = "Tutorial";
Info->Author     = "Lizardsoft";
Info->Email      = "software@lizardsoft.com";
Info->Version    = "v1.0";
Info->Copyright  = "Copyright (C) 2002-2004, Lizardsoft
All Rights Reserved";

Info->FuncInfo = FuncInfo;
Info->FuncAmt  = 2;

Info->FuncInfo[0].SetInfo( "HelloWorld", "", 0, 0 );
Info->FuncInfo[1].SetInfo( "PrintChar", "sis", 2, 0 );

return 1;
}

Providing CustomBar with Information

CustomBar requires all plugins to make certain information available in memory for as long as they are loaded. This includes plugin details such as plugin name and author, as well as a list of plugin functions that the plugin is making available to CustomBar.

When GetPluginInfo() is called, the address of a PLUGIN_INFO structure is passed to your plugin. This structure has been created by CustomBar and requires that you fill it with information about your plugin. Most of the members are pointers to C strings, which must remain valid throughout the lifetime of your plugin. CustomBar does not create its own copy of these strings! It is therefore safest to set these pointers to literal strings, as done in the example.

In addition to information about the plugin, CustomBar also requires a list of every plugin function that the plugin exposes, along with parameter information. This list comes in the form of an array of PLUGIN_FUNC objects. Your plugin is responsible for creating this array, with one entry per function that you expose. You pass the pointer to this array to Info->FuncInfo and set Info->FuncAmt to the amount of entries in this array.

The PLUGIN_FUNC class has a member function called SetInfo(). Use this function to set the information in each PLUGIN_FUNC object, just like in the example above. SetInfo() takes four parameters: the name of the function, its parameter and return type(s), how many arguments it takes, and how many arguments are optional. The function name is simply the same name as the name given to the function that you are exporting. The type string is a list of parameter types. 's' stands for string, 'i' stands for integer, and 'f' stands for float. If there are more characters in the string than the amount of parameters that the function is listed as having, then the last character is interpreted as being the function's return type. If a function accepts no arguments and has no return value, an empty type string should be used. The third parameter is simply the amount of parameters that a prefab's script can pass to the plugin function, including optional parameters. The last argument specifies how many of those parameters are optional.

If you do not understand this process entirely you need not fear. Ultimately you'll just be copy pasting this code from the Tutorial plugin code and modifying it to meet your needs. It uses some C++ concepts, which is another reason why a C++ compiler is required. At this time you should take a break from reading and open up the Tutorial sample in the SDK\Samples\Tutorial folder of the SDK and examine the complete source file. Once you have a firm grip on what has been done so far, continue reading this tutorial.

Declaring Plugin Functions

Every single plugin function that you create, regardless of what parameters and return types it uses, is always declared the same way:

int HelloWorld( P_UNIVAL *Params, P_UNIVAL *Result, PLUGIN_CALLINFO *CallInfo, void *Reserved );

Before examining what this stuff means, let's create a simple plugin function that displays a 'Hello World' message when called. Note that in the GetPluginInfo() function we already created an entry for a function named HelloWorld, and that we set it to have no arguments and no return type.

int HelloWorld( P_UNIVAL *Params, P_UNIVAL *Result, PLUGIN_CALLINFO *CallInfo, void *Reserved )
{
MessageBox( 0, return 1;
}

The meat of this function is only two lines. MessageBox() is a Win32 API function that displays a simple message box. The function then returns 1. Returning 0 will flag an error that will be logged. This can be useful for debugging, but absolutely must be changed to return 1 before releasing your plugin. This error mechanism exists only for returning unrecoverable errors, and in future versions may cause CustomBar to terminate itself. If your plugin function fails to execute correctly, simply fail gracefully and silently.

A successful call to Tutorial.HelloWorld will create this box.

At this point we have managed to create a plugin function without touching any of the parameters passed to it. We will now create a more complex function that accepts parameters and returns a value.

int PrintChar( P_UNIVAL *Params, P_UNIVAL *Result, PLUGIN_CALLINFO *CallInfo, void *Reserved )
{
const char *CharStr = Params[0].GetConstStr();
int Count = Params[1].GetInt();
char Chr;
char *NewStr;
int i;

Chr = CharStr[0];
NewStr = new char[Count+1];

for( i=0; i < Count; i++ )
NewStr[i] = Chr;

NewStr[i] = '0';
Result->SetStr(NewStr);
delete[] NewStr;
return 1;
}

This function accepts two parameters - a string and an integer - and returns a string. It has the questionably useful purpose of taking the first character in a string and creating a new string with that character repeated a specified amount of times.

This time we have to exchange values with CustomBar. Both parameters and return value are handled using the P_UNIVAL object. This is a special type of object capable of morphing between different variables types. The first two arguments to plugin functions, Params and Result, use this object. Params is an array of pointers to these objects - one for each parameter that your plugin function accepts. Result is a pointer to a single instance of this object whose value you set to the result that you want your plugin function to return. Look at how these are used in the example above.

Don't attempt to use the method shown above to accept optional parameters. A section of this tutorial is devoted to optional parameters and explains the special way that these are safely retrieved.

The rest of the mechanics of the example function are simply C string manipulation. Be extra careful to make sure that any memory that you allocate inside a function always gets freed. Considering how often some plugin functions can be called, any memory leaks can quickly grow very devastating.

At the time of this writing the other two arguments that get passed to your function, CallInfo and Reserved, do not yet have a documented purpose. You can safely ignore the values of these parameters. In a future version, CallInfo will be used for more detailed error handling and for implementing unicode support.

Compiling the Tutorial Plugin

Now is the time to test this plugin. Note that if you want something that will actually compile, you need to create a new project in your development environment, and add the sample Tutorial.cpp file in the SDK\Samples\Tutorial folder of the SDK. If you create the project within the same folder then it should compile fine without modifying the file. If you place it in a different location, you may need to modify the #include line that includes the SDK header file. Don't forget to link in the CBPluginLib.lib and DataLib.lib libraries! They are located in the main SDK folder. Be sure to also tell your compiler that you want a DLL, not a Windows executable. If you need more help, see the beginning of this tutorial for more detailed instructions on plugin compilation.

Testing the Tutorial Plugin

At this point in time you should have a compiled plugin, probably named tutorial.dll (name doesn't really matter). Copy it to your CustomBar\Plugins folder. Note that CustomBar only attempts to load plugins when it first starts up. This means that you have to shutdown CustomBar entirely and start it again for it to load the plugin. After you have done this check the CustomBar\Logs\Plugins.log.txt file. It should list your plugin as having been loaded successfully with at least 2 functions listed as available.

To actually test the functionality of your new plugin you need to create a CustomBar prefab. A sample prefab is included with the Tutorial plugin code. That file contains all the code listed here, plus the parts that have been omitted in this tutorial for the sake of clarity. The file is located in the SDK\Samples\Tutorial\Test folder. Copy the Test folder into your CustomBar\Prefabs\CustomBar folder, and then add the CustomBar.Test prefab to your bar. If your plugin works successfully, you will see an edit box with 5 stars in it. Right-clicking it should display a hello message. The stars are generated by the Tutorial.PrintChar() function. Here are the two procs used in the sample prefab. Look through the prefab files in notepad to see the rest of the code:

Text = "^Tutorial.PrintChar( '*', 5 )^"
RClickProc = "Tutorial.HelloWorld();"

Debugging Plugins

Writing code without making mistakes is difficult at best. Luckily you have several options for debugging plugins. With smaller plugin functions it is tolerable to simply use a trial and error approach, and to display debug output in message boxes. Advanced compilers such as Visual Studio provide facilities for debugging DLL files that are loaded by another application. This is extremely useful and if you have this functionality available to you then you are advised to take advantage of it. With larger plugin functions it may be helpful to write the core code of the plugin function as part of a test Win32 executable first and turn it into a plugin after you have verified that the code works.

Conclusion

This is it for the basics of plugin creation. For things like optional parameters and advanced tricks, be sure to check out the source code for the standard CustomBar plugins. It comes installed with CustomBar and is there for your use.


Sample Plugin Source Code

Lizardsoft believes firmly in making it as easy as possible for users of CustomBar to actually take advantage of the customization options that this product offers. In the spirit of this belief, the source code for all standard CustomBar plugins is available and installed by default with CustomBar. The purpose of releasing the code is to provide real working plugin examples for plugin developers, and to subject the standard CustomBar plugins to peer review.

There are two sets of plugins with source code available:

1. Standard Plugins

2. Tutorial Plugins


License for Sample Plugins

License

The following CustomBar plugins and corresponding source code are being released under the GNU Lesser General Public License:

1. AudioPlayer (Plugins\AudioPlayer.dll)

2. String (Plugins\String.dll)

3. System (Plugins\System.dll)

4. System Info (Plugins\SystemInfo.dll)

5. Tutorial Plugins (SDK\Samples\)

Please read the full GNU Lesser General Public License below before using this code.

          GNU LESSER GENERAL PUBLIC LICENSE
               Version 2.1, February 1999

 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
    59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
 as the successor of the GNU Library Public License, version 2, hence
 the version number 2.1.]

                Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.

  This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it.  You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.

  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.

  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.

  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

  We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.

  For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard.  To achieve this, non-free programs must be
allowed to use the library.  A more frequent case is that a free
library does the same job as widely used non-free libraries.  In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.

  In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software.  For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.

  Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.

          GNU LESSER GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".

  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)

  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.

  1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

  2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) The modified work must itself be a software library.

    b) You must cause the files modified to carry prominent notices
    stating that you changed the files and the date of any change.

    c) You must cause the whole of the work to be licensed at no
    charge to all third parties under the terms of this License.

    d) If a facility in the modified Library refers to a function or a
    table of data to be supplied by an application program that uses
    the facility, other than as an argument passed when the facility
    is invoked, then you must make a good faith effort to ensure that,
    in the event an application does not supply such function or
    table, the facility still operates, and performs whatever part of
    its purpose remains meaningful.

    (For example, a function in a library to compute square roots has
    a purpose that is entirely well-defined independent of the
    application.  Therefore, Subsection 2d requires that any
    application-supplied function or table used by this function must
    be optional: if the application does not supply it, the square
    root function must still compute square roots.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

  4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

  5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

  6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:

    a) Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)

    b) Use a suitable shared library mechanism for linking with the
    Library.  A suitable mechanism is one that (1) uses at run time a
    copy of the library already present on the user's computer system,
    rather than copying library functions into the executable, and (2)
    will operate properly with a modified version of the library, if
    the user installs one, as long as the modified version is
    interface-compatible with the version that the work was made with.

    c) Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

    d) If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

    e) Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.

  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

  7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:

    a) Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

    b) Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.

  8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

  9. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

  10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.

  11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.

  13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

  14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.

                NO WARRANTY

  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

 END OF TERMS AND CONDITIONS


Standard Plugins

Lizardsoft believes firmly in making it as easy as possible for users of CustomBar to actually take advantage of the customization options that this product offers. In the spirit of this belief, the source code for all standard CustomBar plugins is available and installed by default with CustomBar. The purpose of releasing the code is to provide real working plugin examples for plugin developers, and to subject the standard CustomBar plugins to peer review.

License

The following CustomBar plugins and corresponding source code are being released under the GNU Lesser General Public License:

1. AudioPlayer (Plugins\AudioPlayer.dll)

2. String (Plugins\String.dll)

3. System (Plugins\System.dll)

4. System Info (Plugins\SystemInfo.dll)

Please read the full GNU Lesser General Public License before using this code.

Components of CustomBar not listed above are not covered by the license. Lizardsoft reserves full rights to and ownership of all other CustomBar source code and binaries.

Note: The following plugin files are also included with CustomBar, but are not true plugins, and exist simply as place holders to allow core components of CustomBar to function correctly: Element.dll, Menu.dll, UI.dll. They are also excluded from the list of components licensed under the GNU Lesser General Public License.

Using the Source

The source code is available in the \PluginSrc\ folder of your CustomBar installation (unless you explicitly opted to omit it) and organized by plugin. It has been successfully compiled with Visual Studio .NET 2003, and will likely work with older versions of Visual Studio. It should be compilable with most other modern C++ compilers with little or no changes. In order to successfully build the plugins, you must remember to link in the CustomBar plugin SDK. Instructions on doing so are elsewhere is this documentation.

It is not necessary to be able to build the entire source in order to benefit from it. The code is a great learning tool and provides plenty of real world examples on accomplishing various tasks. Lizardsoft does not provide support for building or using the source code. If you require assistance, you can try visiting the CustomBar Forums.

How to Submit Code Modifications

Part of the purpose of releasing the CustomBar plugin source code is to allow fellow programmers to review the code and to suggest additions or modifications for incorporation into future versions of CustomBar. This type of peer review will help CustomBar be the fastest and stablest application of its kind.

If you wish to submit a request for changing part of the plugin source, please post in the appropriate forum on http://forums.custombar.net.


Tutorial Plugins

The CustomBar plugin SDK includes the source code to at least one sample plugin. This source is located in the Samples\Tutorial folder of the SDK and is licensed under the GNU Lesser General Public License.


TDSettings Reference

TDSettings is the language that all the .tds files (which includes most CustomBar files) are written in. It was created with the goal of allowing large amounts of program settings to be specified easily. This is the official language reference. If you are interested in manually editing bar files, or creating prefabs, plugins, or skins, it is highly recommended that you read this.

If you haven't already done so, take a peak through a few .tds files using Notepad (your bar file and skin files are a good start). The guide will make much more sense then.

General Format

TDSettings files consist of a list of settings and their values. They may also include categories (specified in square brackets) and category descriptions. Certain special commands provide convenient ways to automate and organize the specifying of a large amount of settings. Below is a simple TDSettings file:

    [DOG]
    Name   = "Rover"
    Age    = 4    ' specified in years
    Weight = 45.5
    Photo  = "\\.\Photos\dog.jpeg"
    Canine = true

    [CAT]
    Name   = "Bob"
    Age    = 2
    Weight = 15.5
    Photo  = "\\.\Photos\cat.jpeg"
    Canine = false

The above example simply sets some values for a dog and a cat. Note that there are several formats for specifying a setting. How a setting is set depends on what data type it is expected to be (these are explained below). DOG and CAT are both categories. Settings specified under a category apply on to that category. Settings placed before any categories are placed into the "default" category. This feature is often used in simpler settings files, where categories are not needed.

The " ' specified in years portion" of the example is a comment. Comments are indicated with a ' character. Any text placed after a ' character until the end of the line is simply ignored by the parser.

Setting Data Types

TDSettings currently supports the following data types for settings. When settings are read from a file, their type is automatically determined based on the format of the value. The data types are as follows:

Integer

This is a 32 bit signed integer. All numerical values that do not contain a decimal character are assumed to be integers.
Examples of Valid Syntax:

    IntVar = 5
    IntVar = -5
    IntVar = 0x31     ' hexadecimal

Float

This is a floating point number. All numerical values that contain a decimal point are created as floating point.
Examples of Valid Syntax:

    FloatVar = -2.5
    FloatVar = 5.0
    FloatVar = 3.4E2

Boolean

This is a special setting that can either be true or false.
Examples of Valid Syntax:

    BoolVar = true
    BoolVar = false

String

Strings are a reasonable length of characters enclosed by quotation marks. See the section marked "Special String Characters" for more information on string syntax.
Examples of Valid Syntax:

    StrVar  = "Hello World"
    StrVar  = "\"I want apples\" said Joe"
    StrVar  = "\.\\test.txt"
    StrVar  = "Hello world, "
              "how are you today?"

Special String Characters

Strings can have special characters/commands, which are indicated with the \ character. The following is a complete reference:

    \\ - represents a normal \ character.
    \" - represents a normal " character.
    \n - represents a linebreak.
    \. - represents the script's full path (minus filename), without trailing
    \#name# - represents value of name, where name is the name of a key in [@CONST] category

Referencing Other Settings

It is possible to reference constants and other settings when assigning a value to a setting with the syntax CategoryName.KeyName. Use
Valid Syntax:

    HotKey  = Keyboard.A    ' assigns HotKey value from Category: Keyboard, Key: A
    MyFood  = this.Food     ' assigns MyFood value from key Food from current category
    Gravity = EarthGravity  ' assigns to Gravity value of constant EarthGravity
    Gravity = .EarthGravity ' assigns to Gravity value of global key EarthGravity

Reserved Category and Key Names

Category and key names must start with a letter. The other characters in the name can be [A-Z], [a-z], [0-9], -, or _. Names also cannot be any of the following reserved words, regardless of case:

    true
    false
    this

Special Category Commands

@SETTINGS

Recommended category for initializing settings such as @IncStart.

@INC

Gives the category the numerical name of the current counter value and increments said value.

See also: @IncStart, @IncLast, @IncCurrent, @IncCount

@CONST

Area for constants to be defined. Should be placed before any categories that make use of constants.

Predefined Constants

@ScriptDir, _ScriptDir

Holds the current script's directory, without the trailing slash. Example:

    TestFile = "\#@ScriptDir#\\test.txt"

See also: Special String Characters, @ScriptFile

@ScriptFile, _ScriptFile

Holds the current script's full filename, without the trialing slash. The path is resolved to its absolute path before being saved, so relative paths are converted to absolute.
See also: @ScriptDir

Special Keys

@IncStart

Sets the counter value for the auto-incrementing category naming counter.
See also: @INC, @IncLast, @IncCurrent, @IncCount

@include = "FileName"

Parses the file FileName and merges its settings with the current file. Things such as auto incrementing counters are created on a per file basis, so the two files cannot directly affect each other's counters.
See also: @template

@template = "FileName"

If FileName is in square brackets, it is recognized as an existing category, otherwise it is assumed to be a file. Similiar to @include, but the category it is used in is the category that receives the settings. For example, if abc.txt is a file with no category specified, and contains the key Name, and another file contains the following:

    [Student]
    @template = "abc.txt"

Then the [Student] category receives the Name key. If the @include command was used instead, then the default category would receive Nsame instead, since @include ignores what category it is called in. Also, unlike @include, @template does not maintain separate incrementing counters between files, allowing @INC categories to span multiple files and still maintain a single counter set.
See also: @include

Special Values

@IncCount

Returns the number of auto-incremented categories created since the last @IncStart. For example, if two [@INC] categories are created and then the @IncCount value is checked, this value will be two regardless of what @IncStart was set to.
See also: @INC, @IncStart, @IncLast, @IncCurrent

@IncLast

Returns the actual numerical value assigned to the last auto-incremented category. For example, if @IncStart is set to 3, then two [@INC] categories are created, the value @IncLast returns will be 4.
See also: @INC, @IncStart, @IncCurrent, @IncCount

@IncCurrent

Returns the actual numerical value that will be assigned to the next auto-incremented category. For example, if @IncStart is set to 3, then two [@INC] categories are created, the value @IncLast returns will be 5.

See also: @INC, @IncStart, @IncLast, @IncCount

Predefined Constants

The following are predefined constants that can be used in any TDS script to access special folders.

    _ScriptDir
    _AppDir
    _WinDir
    _SystemDir
    _ComputerName
    _UserName
    _RecentFiles
    _RecentFilesDir
    _Favorites
    _FavoritesDir
    _MyDocumentsDir
    _MyPicturesDir
    _StartupDir
    _ProgramFilesDir
    _ProgramFilesCommon
    _StartMenuDir
    _StartMenuProgramsDir
    _DesktopDir
    _InternetCacheDir

This reference and TDSettings are Copyright(C) 2001-2004 Lizardsoft. All rights reserved.


About Lizardsoft

Lizardsoft is privately held Canadian software and web services company. Our services include custom software development, web development, and web hosting. For more information about custom development please contact software@lizardsoft.com.

Contact Information

E-mail: | software@lizardsoft.com
Post: | P.O. Box 37002 1005 Ottawa St. N Kitchener, Ontario N2A 2H0 Canada


Web Hosting Solutions

Reliable Web Hosting Solutions

Trust Your Business to a Company That Does Things Right

Lizardsoft Hosting has been founded on the need for web solutions that professionals can rely on. In addition to providing first-class hosting on highly dependable Linux servers, we advise our clients and make sure that their requirements are satisified. By hosting with us, you can be confident that you won't feel lost even if you are new to web hosting.

We back our claims of superior reliability, speed, and support with a 30 day money back guarantee. If you aren't happy, we don't deserve your money.

Complete Hosting Solutions

We offer a wide variety of regular, reseller, and custom hosting packages along with services that include domain registration and custom script development.

All accounts receive access to CPanel and a variety of other tools for easy account management. Servers are kept well below capacity to ensure that every client receives the same great speed and service that Lizardsoft Hosting delivers.

What to Expect When Hosting With Us

Account Setup in 24 Hours or Less
30 Day Money Back Guarantee
Domain Registration Services
Advanced Control Panel

Visit Our Site to Learn More

Learn more about our services and take advantage of our great deals by visiting our hosting site at http://www.lizardnetwork.com.


index

Control.SetText

Sets the control's actual text. Note that this is different from setting the control's TextProc, which updates the control text every TimerRate milliseconds with its contents. This function is mostly used to easily set text in controls such as edit boxes, and for setting large amounts of text. For more information on the differences between SetText and SetTextProc, see the Scripter's Control Documentation

Control.SetText( string NewText, string OldText )

Parameters

NewText

New text to replace control text with.

Return Value

No return value.