Stardock 2.4 User Manual
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 ............................................................................................................... 5
2.1 CREATING A THEME .....................................................................................................................5
Hiding elements .......................................................................................................... 5
Workarea .................................................................................................................... 5
Resolutions ................................................................................................................. 6
Wallpaper and Labels ................................................................................................. 6
Theme Information...................................................................................................... 7
2.2 CREATING AN OBJECT..................................................................................................................8
2.3 OBJECT TYPES..............................................................................................................................9
Layer .......................................................................................................................... 9
Shortcut .................................................................................................................... 10
URL .......................................................................................................................... 10
Object Controller ...................................................................................................... 11
Taskbar..................................................................................................................... 11
System Tray............................................................................................................... 12
System....................................................................................................................... 12
DesktopX .................................................................................................................. 12
Widget....................................................................................................................... 12
2.4 OTHER OBJECT BASICS..............................................................................................................13
Labels ....................................................................................................................... 13
Summary tab ............................................................................................................. 13
Alignment.................................................................................................................. 14
2.5 EXPORTING WIDGETS, OBJECTS AND THEMES ..........................................................................15
3 Enhancing Objects............................................................................................................... 17
3.1 OBJECT APPEARANCE & STATES ...............................................................................................17
States ........................................................................................................................ 17
Image objects............................................................................................................ 17
Image sizing and offsets ............................................................................................ 19
Text Objects .............................................................................................................. 19
Object Transparency................................................................................................. 19
_____________________________________________________________________________
Page 2
DesktopX 2.4 Developer’s Guide
_____________________________________________________________________________
Shadows and Glows .................................................................................................. 20
Color ........................................................................................................................ 20
Sound........................................................................................................................ 20
New States ................................................................................................................ 21
3.2 ANIMATING OBJECTS.................................................................................................................22
Static Animations ...................................................................................................... 22
Image animations...................................................................................................... 23
3.3 THE BASICS OF RELATIONSHIPS ................................................................................................24
Visibility.................................................................................................................... 24
Z-Order..................................................................................................................... 24
Movement ................................................................................................................. 24
Activation.................................................................................................................. 25
Start with .................................................................................................................. 25
Default Cursor .......................................................................................................... 25
Popups...................................................................................................................... 25
Position Adjustment .................................................................................................. 26
3.4 GROUPS, PARENTS AND CHILDREN............................................................................................27
Groups...................................................................................................................... 27
Parents and Children ................................................................................................ 28
3.5 SENDING MESSAGES ..................................................................................................................29
3.6 CUSTOM FILES ...........................................................................................................................30
3.7 DESKTOPX PLUGINS ..................................................................................................................31
Digital Clock............................................................................................................. 31
Digital Clock (Text State).......................................................................................... 31
Email Notify.............................................................................................................. 32
Performance Meters.................................................................................................. 32
DX Player ................................................................................................................. 32
4 Tips and guidelines .............................................................................................................. 33
4.1 DO NOT ASSUME DEFAULT “START WITH” COMMAND..............................................................33
4.2 PLUGINS .....................................................................................................................................34
4.3 CHILD OBJECTS..........................................................................................................................35
4.4 ANIUTIL WITH OPTIMIZATION FOR MAKING ANIMATIONS ........................................................36
4.5 32 BIT IMAGE FORMATS..............................................................................................................36
4.6 SCREEN RESOLUTION ADAPTATION BEFORE DISTRIBUTING YOUR OBJECTS..............................36
4.7 JPG WALLPAPERS.......................................................................................................................36
4.8 METER OBJECTS .........................................................................................................................37
4.9 WRITING “PROPER” SCRIPTS ......................................................................................................37
4.10 BUILDING “PROPER” OBJECTS BROWSING THE INTERNET..........................................................37
_____________________________________________________________________________
Page 3
DesktopX 2.4 Developer’s Guide
_____________________________________________________________________________
4.11 NEVER USE THE SLEEP METHOD IN SCRIPTS ..............................................................................38
4.12 ONLY PACKAGE USEFUL OBJECTS..............................................................................................38
1
Introduction
________________________
1.1 About this guide
Having mastered the use of DesktopX, you are probably ready to start creating objects for
yourself. This may be just a simple object or you may already have grand plans based upon what
you have seen other objects do.
This guide is designed to ease you through the process of creating objects. Don’t feel that you
have to take it all in at once. If you don’t have the time to sit down and read this document then
you should consider skimming the document to get an understanding of what it contains and then
skip to the sections as you need them.
Scripting is a further advancement for creating even more sophisticated objects. The DX
Scripting Guide describes this.
You should also be aware that in addition to this document, you can also obtain help in several
other places:
The Stardock newsgroups are frequented by both Stardock staff and developers. They are
therefore a great place to get advice and help. The news server is news.stardock.com and the
primary group for DesktopX is stardock.desktopx
You can also find help via chat on irc.stardock.com in the #stardock channel.
This document will evolve with future releases. This document is written and maintained by
Martin Conroy so if you have comments or suggestions, feel free to email me
(martin@stardock.com), of visit us in the newsgroup or us on IRC chat.
Have fun!
_____________________________________________________________________________
Page 4
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.
The easiest way to do this is to select ‘New Theme’ from the ‘Theme’ tab on the DesktopX
configuration dialog that you were introduced to in the User’s Guide.
After choosing whether to save your existing theme, you will then be asked to confirm that you
reset all of the existing theme's elements like wallpaper and work areas.
On the ‘Theme’ tab, you will find all the theme related items that you can define. These are ways
of ensuring that the user experience of this theme will be consistent.
Hiding elements
You have two options here. ‘Hide desktop icons’ means that no icons will be displayed on the
desktop, not even IconX objects. By doing this you can be sure that the desktop will be totally
clear. You can also remove the taskbar from the desktop by checking ‘Hide Windows taskbar’.
This will mean that the user has no access to the start menu, running applications, or system tray
unless you create objects to replicate these functions so you should use this option cautiously.
Workarea
This button allows you to fool Windows into thinking the desktop is actually smaller than it is.
Why would you want to do this you may wonder? Well, one example is if you create objects
along the edge of the screen, like the windows taskbar. If you do this without reducing the area
then there are two things that occur; either maximized applications cover your objects so you
can't see them, or your object covers the window so you can't see that. Obviously, you don't
really want this so in this scenario. If you click the 'Work area' button and then check the 'Reduce
work area' box, then enter a number in the 'Bottom' box to specify the number of pixels you want
_____________________________________________________________________________
Page 5
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 provides some advanced features to allow you to
define how individual objects position themselves dependant on changes in the screen resolution.
This section is definitely optional, as if you set up the objects properly DesktopX themes should
work with different resolutions. There will be cases however when themes need to work at
specific resolutions. For example, you may have many objects which won't all fit onto a smaller
screen. Where this is the case, then you should check the boxes of all resolutions at which the
theme is designed to work. Whilst this will not stop users of other resolutions using your theme,
it will at least prompt them that the theme wasn't designed for that resolution, and as such may
not look as it was intended to.
Wallpaper and Labels
Via the two other buttons on this tab, you can define additional visual configuration options.
One of the quickest ways of changing the visual user experience is to use a wallpaper just as you
would on a standard desktop. If you click the ‘Wallpaper’ button you can then ‘Browse’ to find
the wallpaper you would like to use. You can use several graphic formats for wallpaper but using
a JPG will keep the theme as small as possible. You can also specify the visual style of the
wallpaper here, just as you can do in Windows.
You can also choose to use a ‘Solid Color’ on the desktop by checking this option and selecting
a color by clicking the ‘Change’ button.
If you are using the ‘center’ wallpaper style you may want to use the ‘Solid color’ option as well,
so you can define the color of the desktop around the wallpaper when the desktop is larger than
the image size.
All your objects can have a text label, so DesktopX allows you to set a default for these at a
theme level so you can ensure that the color and font is consistent with your theme.
If you click the ‘Labels’ button you can define the color and font in which the label appears.
In both cases you can choose to use the system defaults as defined in the Windows Display
Properties. Alternatively you can custom define them. In this case you can choose the default
color of labels and the color when the item is selected.
When selecting a custom font, if you are going to distribute the theme to other users make sure
that they will have the font on their machine as well. Alternatively, subject to copyright issues,
_____________________________________________________________________________
Page 6
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.
_____________________________________________________________________________
Page 7
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.
On the DesktopX Settings dialog, you can simply click ‘New’ on the ‘Objects’ row or the Theme
tab.
There are two other ways to do the same. If you right click the DesktopX icon on the system tray
you can then select 'New object' from the menu that appears.
Where you have hidden desktop icons in a theme, you can also get this menu by right clicking on
the desktop.
When you select this a basic object will appear on the desktop ready for you to customize.
When you do this the 'Object Properties' dialogue will also be displayed to allow you to start
configuring your object.
This is where all the fun begins!
_____________________________________________________________________________
Page 8
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.
Once a type is defined, the activity associated with that object type will occur when an object is
clicked, though the object's ‘Start with’ parameter can be changed to alter when this occurs.
Doing this is sensible as you can’t be sure what the default activation action is defined by the
user. More on this later.
We will go through each of these items in turn and explain how to use them. I encourage you to
try them out as you go and experiment with the functionality on offer. This is the best way to
learn.
Different object types will have a range of options. For a layer, you can choose to make it
'Accept Drag & Drop'.
Layer
The default type of object created is a 'Layer'. A layer object doesn't interact with the user in any
way. There are several reasons why you may want objects of this type. It may be a text label
proving information to the user, or it may just be a graphic enhancing the visual experience for
the user.
Normally, you can drag files from applications (e.g. Explorer) onto the desktop to create a
DesktopX object which links to that file. If you select this option for a layer, it means that if you
drag a file on top of it, it becomes ‘Contained’ within that object and moves when the ‘Parent’
object moves.
_____________________________________________________________________________
Page 9
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).
In addition to the specific paths that you can enter, DesktopX provides several variables that can
be used to point to specific directories.
%exedir% - returns the executable directory.
%objectdir% - returns the object data directory (where custom files are stored).
%objectsdir% - returns the full \Objects directory.
%themesdir% - returns the full \Themes directory.
So, for example, if you wished to link to one of the default clock objects that comes with
DesktopX, you could link to this “%objectsdir%\Nicer Analog clock.dxpack”
If you choose a 'Folder shortcut', you can either choose a system folder such as the Control
Panel, or you can choose to browse for any folder on your computer. In either case, this will
cause an Explorer window to open displaying the contents of that file.
You can however, check the box below the dropdown menu to popup a menu of the contents of
that folder. You can then click an item on that menu to run that item directly. You can even
specify where the menu appears relative to either the cursor or object itself.
What you should know is that these objects will function like the real target of the shortcut. For
example, if you drag the file c:\mydoc.txt to an object which is a shortcut to Notepad.exe then
that file will open up in Notepad. Dragging a file to a folder shortcut will move or copy the file
to that actual folder.
URL
A 'URL' object type is similar to the shortcut but it is dedicated to launching web pages in your
browser, so all you need to do is enter the web address (e.g. www.wincustomize.com).
_____________________________________________________________________________
Page 10
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. We will define how to do this later, but at the
moment it is enough to know that you can select one of the first 2 options here to show or hide
the object.
You can also choose to 'Destroy' an object. This might seem somewhat destructive, but is
sometimes useful. For example, when a theme is loaded you may want to display a welcome
message to the user. You don't want this after it has been read though, so you may set it so it
destroys itself when clicked.
Obviously these commands mean nothing without specifying which object is the target of this
action. You do this by selecting the object from the 'Target object' dropdown list.
Taskbar
The 'Taskbar' object offers some immediate functionality. This transforms the object into a
display of the applications running on your machine.
Obviously there are a few configuration options to adjust how you want the taskbar to look.
You can choose whether the taskbar runs horizontally or vertically, and at which end of the
taskbar new items are added, and the size of the icons used to represent the items on the taskbar.
If you want, you can add labels which display the name of the application, and choose the color
of the text used dependant of whether the item is selected or not.
The final 4 items really define the structure of the taskbar. The first item lets you define how
much space the maximum size of each item on the taskbar. Essentially this defines how wide (in
pixels) each item will be where 'Use labels' is selected.
You also need to specify how much space there is between items. The final option allows you to
vertically offset the contents of the taskbar. This may be important depending on the graphic
used in your object. The graphic is defined like any other except you get a customized
'Advanced' option which you need to make good use of to customize the object. We will get onto
this in the appropriate section.
Normally, the taskbar just grows and shrinks depending on the number of items in it, but the
final option is a check box that allows you to lock the size of the taskbar. When this option is set
the size is defined by the height or width option on the Object Properties 'Summary' tab
(depending on the taskbar orientation). This value can be an absolute number of pixels (e.g. 400),
or a percentage relative to the screen width (e.g. 80%).
_____________________________________________________________________________
Page 11
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. Each
of these items has a corresponding Windows dialogue box that will be displayed when the user
interacts with the object.
DesktopX
The 'DesktopX' class provides you will a list of things to do that relate to DesktopX and it’s user
interface. Each of these items is fairly self explanatory.
Widget
This class is useful if you are planning to export the widget as a stand alone Executable file (or
widget). You can use these to replicate the commands that are available in Widgets – to close the
widget, minimize it, or display the About box. Widgets are explained in more detail in section
2.5.
_____________________________________________________________________________
Page 12
Loading...