Canvas Controls

Desktop Sidebar provides several controls to display different kinds of data on your panel.

All controls share a few common attributes.

Common Attributes

Attribute NameTypeDescriptionValues
id Optional The control's internal identifier for use in the panel's code. Any unique name (can't be the same for two controls).
display Optional Whether the control is displayed or not. "0" = the control is hidden, as if it was not there at all.
"1" = the control is displayed.
visible Optional Whether the control is visible. "0" = the control is invisible, but does occupy space in the canvas.
"1" = the control is visible.
zorder Optional Determines which control will be on top of which. A number. A control with a higher z-order value will be in front of a control with the lower z-order. Highest z-order is the topmost control.

Image

Displays an image from a file on the panel.

Tag: <image>

Attributes

Attribute NameTypeDescriptionValues
src Required The path to the image file that the control will display. Path to an image file - PNG, JPG, GIF, BMP (absolute path or relative to the .dsplugin file's location)
opacity Optional The image's transparency value A number ranging from 0 to 255:
"0" = transparent
"255" = fully opaque

Button

A clickable button with a skinnable background image.

Tag: <button>

Attributes

Attribute NameTypeDescriptionValues
check Optional The initial state of the button (if you wish it to function as two-state - see explanation below). "0" = button is not checked
"1" = button is checked
style Optional A normal button will fire the click event only once when clicked. A continuous click button will continue firing the click event in short intervals until released. "0" = normal button
"1" = continuous button
baseskin Optional Determines what skin element will skin the button. A skin element name (open the Desktop Sidebar Skin Editor to see the possibilities)

Events

EventWhen?Parameters
click Whenever the button is clicked None

The button may function as a two-state button: it starts as unchecked, and when clicked becomes checked, clicking again will cause it to become unchecked, and so on. When in the checked state, the button can use a different skin element. This is done like the following:

<button baseskin="buttonSkinNormal"> <skin id="checked" baseskin="buttonSkinChecked" /> </button>

Text Output

Displays any text on the panel.

Tag: <textoutput>

Attributes

Attribute NameTypeDescriptionValues
text Optional The text that will be displayed in the control (it can later be changed in the code) Any text
wrap Optional Whether text will be wrapped to the next line if there isn't any room left "0" = no text wrapping
"1" = text will be wrapped
baseskin Optional Determines what skin element will skin the control's appearance A skin element name (open the Desktop Sidebar Skin Editor to see the possibilities)

Events

EventWhen?Parameters
click Whenever the text output is clicked None
mousehover Whenever the mouse is moved over the text output None
mouseleave After the mouse is moved out of the text output None
showdetails Whenever a Details Window should be shown (may be on click, on mouse-over, or never, depending on the user's chosen preference in Desktop Sidebar's Options. None

List Output

A scrollable list of items.

Tag: <listoutput>

Attributes

Attribute NameTypeDescriptionValues
autoscroll Optional Whether scroll buttons will automatically be added to the list "0" - scroll buttons will not be shown, even if some rows are hidden
"1" - the list will have vertical scroll buttons to enable scrolling it if it's too long to fit the available space.
wrap Optional Whether a row's text will be wrapped to the next line if there isn't any room left "0" = no text wrapping
"1" = row text will be wrapped
maxfitrows Optional The maximum number of rows that will be shown if the list is too long (use in conjuction with autoscroll="1") A number
separator Optional Whether a separating line will be painted inbetween each line (note that some skins disable separators so you might not always see them) "0" - no separators
"1" - separators will be shown
righttoleft Optional Whether text in the list will be shown in the RTL reading direction (from right to left) "0" - right to left
"1" - left to right
textindent Optional The text indentation: the distance, in pixels, of the first letter of the text from the left edge of the panel A number (pixels)
tabs Optional A comma-separated list that specifies the width of each tab. Will only be used if a row's text will contain the TAB character ("\\t"), like: "First Tab Here\\tSecond Tab Text". A number (pixels)
baseskin Optional Determines what skin element will skin the control's appearance A skin element name (open the Desktop Sidebar Skin Editor to see the possibilities)

Events

EventWhen?Parameters
click Whenever a row in the list is clicked
  1. listOutput - the originating list output control object
  2. row - the row object representing the row that was clicked
mousehover Whenever the mouse is moved over a row in the list
  1. listOutput - the list output control
  2. row - the hovered row
mouseleave After the mouse is moved out of the list output
  1. listOutput - the list output control
  2. row - the row that was left
showdetails Whenever a Details Window for a row should be shown (may be on click, on mouse-over, or never, depending on the user's chosen preference in Desktop Sidebar's Options.
  1. listOutput - the list output control
  2. row - the row requiring the Details Window
scrolled Whenever a Details Window should be shown (may be on click, on mouse-over, or never, depending on the user's chosen preference in Desktop Sidebar's Options. None

Bar Chart

A chart that displays numeric values in a graphical way.

Tag: <barchart>

Attributes

Attribute NameTypeDescriptionValues
type Optional The type and appearance of the chart. Default is a bar chart displaying percent "0" - bar chart displaying percent value
"1" - bar chart displaying numeric value
"2" - vertical bar chart displaying numeric value
"3" - horizontal bar chart displaying numeric value
"4" - graph
"5" - histogram
"6" - horizontal progress bar
"7" - vertical progress bar
"8" - analog chart
"9" - pie chart
"10" - text only (no graphical chart)
label Optional The textual label displayed next to the chart Any string (preferably short, an abbreviation)
min Optional The minimal value of the chart A number
max Optional The maximal value of the chart A number
value Optional The initial value of the chart A number ranging between the minimum (min) and maximum (max) values of the chart
textposition Optional Where the label will be positioned in relation to the chart "0" - horizontal text to the left of the chart
"1" - horizontal text to the right of the chart
"2" - horizontal text above the chart
"3" - horizontal text below the the chart
"4" - vertical text to the right of the chart
"5" - vertical text to the right of the chart
"6" - vertical text above the chart
"7" - vertical text below the chart
"8" - to label at all
textcolor Optional The color of the label's text A hex number representing the color, e.g. "#00FF00" is green
valuevisible Optional Whether the value displayed in the chart will also be written as text (by default it is) "0" - value text is hidden
"1" - value is shown as text too
suffix Optional A short string that will be appended to the value and displayed in the chart (for example, "%", " MB", etc.) Any short string

Events

EventWhen?Parameters
click Whenever the chart is clicked None
mousehover Whenever the mouse is moved over the chart None
mouseleave After the mouse is moved out of the chart None
showdetails Whenever a Details Window for the chart should be shown (may be on click, on mouse-over, or never, depending on the user's chosen preference in Desktop Sidebar's Options. None

Marquee

Display short text that scrolls sideways on the screen.

Tag: <marquee>

Progress Bar

A colored bar used to visualize how much of a process is completed.

Attributes

Attribute NameTypeDescriptionValues
min Optional The minimum value of the progress bar Any number
max Optional The maximum value of the progress bar Any number
value Optional The initial value of the progress bar Any number ranging between min and max

Slider

A trackbar and thumb that can be dragged by the user to change the value.

Tag: <slider>