nikita.melnichenko

November 22, 2024

The purpose

Plasmoid is meant to show a progress of your tasks in a convenient form. You can have static progress states and set the completed part manually or you can use dynamic progresses that have a constant speed, timers or poll data from external sources. A supplemental data engine (installed separately) adds DBus interface to the plasmoid. This means you can access values from a command line and from any other program. This thing even let you control your script from the plasmoid (pause it or let it go).

You can have multiple progresses on one plasmoid. This keeps things organized in groups and saves a space. Plasmoid have a few visual interfaces and allows you to setup their style. Everything is done to give you the whole picture on your tasks and to let you manage your time better.

Another useful feature is an action that's executed when progress state becomes equal to 100%. It could be a message through a standard KDE notification system or launch of external program. See detailed description of all these features below.

Progress types

There are different types of progress items available in the plasmoid. Each has its own set of parameters that are shown on the Behavior tab of a configuration dialog.

To add a new item use a popup menu.

To delete an item use Delete button in the configuration dialog of this item.

Basic

This is the most simple progress state. You need to set up an interval of values and a current value. The progress also have a variable title that is commonly used in messages and a invariable name used in DBus.

Live

It's a dynamic progress. It has a constant speed, update interval, i.e. how often the value is increased, and a button to start and stop it.

Timer

The same as a live progress but the speed is always equal to 1000 points per second and the value is a number of milliseconds from the start. In simple words it's just a usual timer.

Poll

This kind of progress gets values from an external program. All you need to set up is a command line and update interval. Plasmoid will launch the command and it should reply a number that's treated as a new value or a set of parameters in the form {"minimum":0,"maximum":100,"value":77}. The poll also has a running state so don't forget to activate it. This state could be used for disabling a poll for some time without clearing a command.

Interfaces

A number of visual representations are available in the plasmoid. Each has its own set of parameters that are shown on the Style tab of a configuration dialog.

Circles interface

The default and probably the most beautiful interface. Each progress is displayed as a circle and all these circles have the same center. Buttons are aligned horizontally.

The following parameters are available for configuration:

• Colors: foreground and background, borders.
• Increasing direction: clockwise or counterclockwise.
• Starting point: on the top, on the right, on the bottom or on the left.
• Displayed part: elapsed or remaining. This is for forward or countdown timers.

Bars interface

Each progress is displayed as a vertical bar. Buttons are aligned vertically near the center of a bar.

Currently only colors are available for configuration.

Meters interface

This interface is experimental and unfinished. It utilizes standard Plasma progress bars and labels that show title and percentage.

Foreground colors are available for configuration but didn't displayed anywhere yet. It's not supposed to be used on panels.

Buttons

Each progress contains configure button that calls a dialog for that progress. If progress type is 'Live' or 'Timer' a running control button is also appeared. If progress is stopped, button starts it, if it's started, button stops it. When progress is finished, button resets its value to the minimum value.

Visibility of buttons is configured in plasmoid settings.

Actions

You can configure actions for executing on progress finish (when percentage = 100%).

A message

Show a message via standard KNotify system. The type of KNotify event (Notification, Warning or Error) has influence on sounds by default. You can configure exact behavior in System settings. The message is a template where you can insert %{name} and %{title} as a placeholders. The timeout defines how long the message would wait for you in the Recent notifications. Zero value means «always».

A command

Setup a command to launch. Arguments can be supplied but should be properly escaped.

Global settings

General

• Name. This is used in DBus for composing a bus name.
• Interface.
• Background: Transparent, standard or translucent.
• Theme: Black and white, Grey zebra or Rainbow. Themes are used to initialize a style of new items.
• Visibility of buttons.

These are background types. As you can see transparent background gives more space for drawing area because borders are not shown.

This is the reason why transparent background is always used on panels. By the way, bars seem to be the most suitable interface for panels.

These are bundled themes.

Default action

The same form as for a single progress. These settings are inherited when new progress item is created.

DBus integration

The data engine

Plasmoid DBus interface is provided by Make Progress! engine that should be installed separately. Plasmoid is fully functional without it, however, the engine opens extra features and lets external programs control plasmoid or read its data. The qdbus utility which comes with Qt framework provides a convenient way to communicate with plasmoid. Launch it without parameters and qdbus will return all registered bus names. If everything is properly set up, you will see
name.­melnichenko.­nikita.­make-progress.­PlasmoidName
on the list, where PlasmoidName is the name from Global settings. Note that current version doesn't support «hot» rename and you should restart the Plasma or live with the current name until that. Let's have a quick look on the interface.

List of items

Suppose that plasmoid name is «main».

# qdbus name.melnichenko.nikita.make-progress.main

/
/i1
/i2
/i3

Here are the root object and three progress items that were created earlier.

The root object

# qdbus name.melnichenko.nikita.make-progress.main /

method QString org.freedesktop.DBus.Introspectable.Introspect()
method QString name.melnichenko.nikita.AddItem(QString type)
method QString name.melnichenko.nikita.Author()
method QString name.melnichenko.nikita.Homepage()
method QStringList name.melnichenko.nikita.Items()
method bool name.melnichenko.nikita.RemoveItem(QString name)
method QString name.melnichenko.nikita.Version()

• AddItem method creates new items. It requires one parameter, the progress type. Returns the name of a new item.
• Items is just another way to list all item names without slashes.
• RemoveItem method removes item by given name and returns true, if operation was successful.
• Author, Homepage, Version are informational.

Example of creating and deleting items:

# qdbus name.melnichenko.nikita.make-progress.main / AddItem 'Basic'

e1

# qdbus name.melnichenko.nikita.make-progress.main / Items

i1
i2
i3
e1

# qdbus name.melnichenko.nikita.make-progress.main / RemoveItem e1

true

# qdbus name.melnichenko.nikita.make-progress.main / RemoveItem i2

true

# qdbus name.melnichenko.nikita.make-progress.main / Items

i1
i3

A progress object

Progress objects could have different sets of methods depending on progress type.

# qdbus name.melnichenko.nikita.make-progress.main /i1

method QString org.freedesktop.DBus.Introspectable.Introspect()
method double name.melnichenko.nikita.GetMaximum()
method double name.melnichenko.nikita.GetMinimum()
method double name.melnichenko.nikita.GetValue()
method void name.melnichenko.nikita.SetMaximum(double value)
method void name.melnichenko.nikita.SetMinimum(double value)
method void name.melnichenko.nikita.SetValue(double value)
method QString name.melnichenko.nikita.Type()

# qdbus name.melnichenko.nikita.make-progress.main /i3

method QString org.freedesktop.DBus.Introspectable.Introspect()
method double name.melnichenko.nikita.GetMaximum()
method double name.melnichenko.nikita.GetMinimum()
method double name.melnichenko.nikita.GetSpeed()
method double name.melnichenko.nikita.GetValue()
method bool name.melnichenko.nikita.IsStarted()
method void name.melnichenko.nikita.SetMaximum(double value)
method void name.melnichenko.nikita.SetMinimum(double value)
method void name.melnichenko.nikita.SetSpeed(double value)
method void name.melnichenko.nikita.SetValue(double value)
method void name.melnichenko.nikita.Start()
method void name.melnichenko.nikita.Stop()
method QString name.melnichenko.nikita.Type()

• Set*, Get* are setters and getters for progress properties.
• Type return the progress type.
• Start and Stop methods control a running state, IsStarted returns it. These methods are defined only for 'Live' and 'Timer' progress types.

Example of controlling a progress:

# qdbus name.melnichenko.nikita.make-progress.main /i3 Type

Live

# qdbus name.melnichenko.nikita.make-progress.main /i3 SetValue 20

# qdbus name.melnichenko.nikita.make-progress.main /i3 GetValue

20

# qdbus name.melnichenko.nikita.make-progress.main /i3 SetSpeed 2

# qdbus name.melnichenko.nikita.make-progress.main /i3 Start

# qdbus name.melnichenko.nikita.make-progress.main /i3 IsStarted

true

# qdbus name.melnichenko.nikita.make-progress.main /i3 GetValue

34.8

# qdbus name.melnichenko.nikita.make-progress.main /i3 Stop

# qdbus name.melnichenko.nikita.make-progress.main /i3 IsStarted

false

# qdbus name.melnichenko.nikita.make-progress.main /i3 GetValue

51.58

Controlling the plasmoid from a script

If your script is processing many objects for a long time then you probably want to display the progress on the plasmoid. You need AddItem and RemoveItem of the root object to create and delete item, SetMaximum and SetValue of the progress object to control current state. Download an example of such a script.

Controlling a script from the plasmoid

The idea is to read a running state of the progress used in the previous example to determine if user stopped processing or started it again. First, create a live progress instead of basic, set speed to zero and start the progress. Each time you need to process another item check result of IsStarted and if it isn't true then wait until it becomes true. This is an example script.

From a user's point of view. He starts the script, a new progress appears and starts increasing its value. User clicks Pause button. Processing pauses. User clicks Play button. Processing continues. Cool, ha?!

Dependencies

• KDE SC 4.4.1 or above.
• PyQt 4.7 or above (for Qt 4.6 or above).

License

The GNU General Public License (GPL), Version 2.

Download and install

Plasmoid

Current version: Plasmoid Make Progress! 0.1.3.

You can install it from GUI but it often freaks out. If you can't upgrade normally then try to remove the old version first.

Install/upgrade from console:

# plasmapkg -u make-progress-0.1.3.plasmoid

Remove from console:

# plasmapkg -r name.melnichenko.nikita.make-progress

Engine

Current version: Data engine Make Progress! 0.1.3.

Install/upgrade from console:

# plasmapkg -u make-progress-0.1.3.engine -t dataengine

Remove from console:

# plasmapkg -r name-melnichenko-nikita-make-progress-engine -t dataengine

Discussion

You can ask questions and suggest ideas in the corresponding topic of the blog or by sending emails directly. There is also the project page on KDE-Look.org, but only registered users are allowed to comment there.

Known issues

Some of these issues are just tasks with low priority that were not finished before the deadline of Javascript Jam.

• If you change a name of plasmoid in the settings, DBus bus name remains the same until Plasma is restarted. It's possible to fix it. By the way, you can restart Plasma without exit from KDE. Execute "kquitapp plasma-desktop" and then "plasma-desktop".
• Meters interface freaks out, doesn't work on panels, no colors there. It's possible to fix it.
• DBus interface sometimes remains while plasmoid is removed. Seems to be a bug in bindings, needs detailed inspection.
• All plasmoids have the same DBus interface in some activities. This is because they create some kind of shared engine but it's not meant to work in this way. Seems to be a bug in bindings or unpredicted behavior, needs detailed inspection.
• Plasmoid doesn't work properly in plasmoidviewer in KDE SC 4.6 (see Plasma bug #271533). It needs to be fixed by KDE team.

ToDo list

Some features are not possible yet due to limits of Javascript API. They are marked with [no API] tag.

• fix issues that are possible to fix
• new progress type: time interval
• cycled notifications
• flashing animation for finished progresses
• item remove button on plasmoid
• custom width of bars, circle paths
• custom svg for bars
• reordering of items
• hidden items
• convenient configuration on panel where buttons are too small
• add shadows for nicer design
• save a full set of style parameters that user already set up for other interfaces
• option to show titles and percentage on circles and bars
• [no API] tooltips for showing title and value of progress (needs tooltip bindings)
• [no API] dragging on progress to change value (needs bindings for mouse events)
• [no API] reorder by dragging (needs bindings for mouse events)
• [no API] native dialogs for items (needs bindings for custom dialogs)

Awards

1st Runner Up and Creative Genius label in the 2010 KDE Javascript Jam Session.

Thanks

• to Aaron Seigo for providing help and support to all contestants during the Javascript Jam session and for fixing vital bugs in bindings
• to Ulf Sauer for tests and bug reports
• to KDE team for the great desktop environment

Change log for plasmoid

Change log for engine