Stardock Developer’s Guide Version 2.4 December 14th 2004 Copyright © 2004 Stardock.net, Inc.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Contents _________________ 1 Introduction ........................................................................................................................... 4 1.1 ABOUT THIS GUIDE .......................................................................................................................4 2 Development Basics .....................................................................
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Shadows and Glows .................................................................................................. 20 Color ........................................................................................................................ 20 Sound........................................................................................................................ 20 New States .............
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 4.11 4.12 NEVER USE THE SLEEP METHOD IN SCRIPTS ..............................................................................38 ONLY PACKAGE USEFUL OBJECTS ..............................................................................................38 1 Introduction ________________________ 1.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 2 Development Basics _____________________________________ 2.1 Creating a theme If you are planning to start working on DesktopX objects it is often easier to start with a blank canvas so you aren't distracted by other objects on your desktop.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ to reduce the desktop by. Once you have done this then applications (when maximized) will not intrude into this space so your objects are visible. Resolutions There is also a 'Resolutions' button so you can specify the screen resolutions your theme is optimally designed to work with.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ you can add the font as a custom file and it will be distributed with your theme and automatically be installed. Theme Information When you come to save your theme you can enter some information about the theme to inform the user what it contains and give credit to anyone who has supported you.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 2.2 Creating an Object OK, so we've done the background work and now it's down to the good stuff. The majority of the rest of the Developers Guide is dedicated to objects and all that they can do. What you'll be pleased to know is that the actual creation of a basic object is very simple. There are several ways that you can create a new object.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 2.3 Object Types To change the object type, click the 'Change' button next to where it says 'Type of object' in the ‘Object properties’ dialogue. This will present you with a list of the other basic object types you can use without having to even consider plugins or script.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Shortcut A ‘Shortcut’ allows the object to link to a file or a folder on your machine. If you choose a file (e.g. Notepad.exe) you can add arguments to that link. For example, if the file shortcut was Notepad.exe, you could add the argument ‘c:\mydoc.txt’ which would launch Notepad and then open the file ‘mydoc.txt’. You can also how that application will appear when launched (e.g. maximized).
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Object Controller Objects can interact with other objects and this is a way to carry out some of the most common of these interactions. An individual object or groups of objects can be defined as 'popups', which means that they can be shown on screen only when they are required.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ System Tray Once you have understood the taskbar type, the 'System Tray' class is easy, as it uses a subset of these options that creates an object to display the icons in your system tray. System The 'System' class allows you to access some of the other standard Windows functionality. Selecting this class provides you with a dropdown list of items from which you can select.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 2.4 Other Object Basics The object is now created in a rough form, but now is an opportunity to run through the other basic elements relating to objects before we move onto more complex things. Labels The first thing you can do is to add a text label to your object. You simply do this by entering the label text into the 'Label' box at the top of the General tab.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ The Object Navigator will show you all your objects, relationships they have with other objects, position and size, z-order and images used. It is not designed to tell you everything, but rather a summary reference that you can use to identify and tweak objects.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 2.5 Exporting Widgets, Objects and Themes OK, you've learnt the basics of creating objects, but now you need to know how to export Objects and Themes. First thing to note quickly, is that though it's a great idea to save your work frequently, every time you click OK or Apply on a dialog, the current work on the desktop will be saved and then reloaded next time DesktopX is reloaded.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Remember that if you create a normal “.dxpack” you can upload your work to the WinCustomize website. By doing this others can benefit from your creations and you may get feedback from users that helps you develop in the future. DesktopX Pro users have a third export option.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3 Enhancing Objects ____________________________________ 3.1 Object Appearance & States OK, well done, you've conquered the basics.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ transparency information with the file, which means that although the saved image may be a rectangle, the actual image that you see on your screen can be any shape you want, because the background is visible when transparent areas of the object exist. This image on the left is a PNG image created in Macromedia Fireworks with a checkerboard effect showing the transparency.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Image sizing and offsets Once you have selected the image to use you can distort the image by entering a width and height for the image in the appropriate boxes. DesktopX is not content with sizing objects in such a brutal fashion, so provides an advanced tab to allow you to resize the image more intelligently. Clicking the 'Advanced' button brings up a new dialog.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ The final option allows you to vary opacity as the object animates but we will discuss that in the appropriate section. Shadows and Glows The ‘Shadow/Glow’ tab allows you to apply either a drop shadow on the object giving it the appearance of floating above the desktop, or a glow surrounding the object. If you click “Enabled” button you can specify four parameters to customize the shadow.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ New States You now know the basics of configuring a single state object. A multi-state object is no more complicated. To add a new state, simply click the 'Add' button.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.2 Animating Objects Whilst everything you learnt in the previous section was great, there's nothing that catches the eye like movement, so DesktopX makes it easy for you to add animation to your objects. The ‘animation’ tab is where you can define how your object animates. The first thing to explain is that there are the two different types of animation that DesktopX can do.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Image animations We will now look at actually animating the image itself, rather than just animating the transparency. Though I said that this is more complicated, it still isn't actually that difficult. The change you need to make is to combine all the frames of the animation into your source image. What you need to do is place the frames of the animation side by side from left to right.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.3 The Basics of Relationships You've already learnt about how the objects you create can interact with the user, and will now learn how they interact with each other. DesktopX allows you to tweak how they interact with users, but also how they interact with the desktop and other applications on screen.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Activation 'Activation' defines how the user can interact with the object. If the setting is 'Default' then it simply follows the user's settings, but you have three other options. 'Rectangular' activation is based on the size of the source graphic and ignores any transparency in the object, whereas 'Visible Area' means that only those areas of the object visible on screen can be interacted with.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ must have a different Object Controller to the original one to close them. Think of them like a normal program. Clicking a link to a program will open it, but clicking the link again will not close the application. A separate 'Object Controller', the close button, is required to do this. 'Toggle' popups - Are the simplest types.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.4 Groups, Parents and Children When developing you will soon realize that many of the best objects are created by several objects working together. For example, consider a simple 'button' made up of a single image. Whilst this may be a good object, it's not very flexible.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Parents and Children 'Parent / Child' relationships are slightly more intimate in that an object is more directly affected by changes made to its Parent/Owner. Again, in the same section there is a 'Parent/Owner' dropdown list where all the other objects in the theme are listed. Simply select one of them and your current object becomes a child of that object.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.5 Sending Messages Sending messages in DesktopX is actually a really simple concept to understand and simple to achieve. In summary, sending messages means that when a user interacts with one object, cause one or more different objects to react. Consider a light in your room. When you flick the switch it changes state, but also the light bulb itself changes state.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.6 Custom Files In the summary tab, there is a button labeled “Custom Files”. This allows you to attach files to objects just as you would do to email that you send. The first reason that you may wish to do this is to attach fonts to a package. If you have text objects that use a font that you are not sure a user has on their machine then you can attach them as a Custom File.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 3.7 DesktopX Plugins DesktopX is a flexible program that opens itself up to developers who can create plugins. These are additional modules providing packaged functionality that you as a user can access. To create an object based on a plugin simply create an object as normal, then in the 'Additional Abilities' section of the 'General' tab, click the 'Add' button.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ Email Notify You can configure this plugin by entering your mailbox details and how often you want to check. The way it works it to create two new Custom states (you recall we mentioned these earlier?) called 'New mail' and 'No new mail'. You can define each of these states to be representative of whether you have mail of not. These could be images or simply different text.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 4 Tips and guidelines ____________________________________ Before using an object you created, and most important before releasing it to other users, be 100% sure that everything is perfect and polished. Below there are a few tips to help you do this. 4.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 4.2 Plugins Starting with latest DesktopX 2 builds, the plugins issue has become more important, and a black list is now in action (it is located in the DesktopX directory and can be edited to add or remove listed plugins). A first distinction is between so called “Old-style" plugins and “SD plugins”. The old style plugins were built around the first very old plugin interface of DesktopX.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ - “Charts and graphs for scripts” (DXChart.dll) – Used by scripts to show statistics in a graphical way. These plugins are distributed with the latest DesktopX2 distributions. If you have doubts about which plugin to use, want to report bugs, or suggest new plugins or updates, feel free to write in news.stardock.com/stardock.desktopx. 4.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 4.4 AniUtil with Optimization for making animations AniUtil is a little utility distributed with DesktopX that let you attach single frames into one "animated" image. It supports bitmaps and PNG. One option is Optimization. It will basically analyze and cut image borders that are not used by any frame.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ 4.8 Meter objects Be aware when building objects that show and update information (i.e. using the DXPerf4 plugin or browsing information from the internet or checking the mail with the mail notify plugin). Too frequent updates of many objects at the same time could cause slow downs, so it is very important to tune every information object carefully. I.e.
DesktopX 2.4 Developer’s Guide _____________________________________________________________________________ in fact it is more similar to the Internet Explorer Online/Offline status, that’s independent from the actual network connection status. A tentative protocol works like this: - Have a global script variable, e.g. IsConnected. - When IsConnected is changed to TRUE, the object can update and retrieve info from the Internet. It can also start a timer to periodically do that.
