xfdce4-timer-plugin: Help

[Jerry Bond]

Hi Devs --

I have been struggling to get this plugin to work correctly after
participating in an old Forum thread
<https://forum.xfce.org/viewtopic.php?id=6823> that has recently been
revived. It is important to us because users frequently ask about
alarms/timers and we would like to be able to point to this.

Part of the problem is the GUI itself, about which I will post at a later
time. I will say en passant that it is remarkable that there is no Help
button on the GUI; the user has to first know there is one and where it is,
then go and consult it--a slow, cumbersome and annoying procedure.

But for now I am interested in trying to bring the Help file up to a level
that would be useful to a wider audience. I provide here a possible
revision of the current doc that aims for 3 goals: 1) update terminology
for titles, labels, etc; 2) clarify various obscure features; and 3)
suggest changes to make the entire document more user-friendly.
==================
==================
*NOTE: images need updating*

====== Timer ======
This is a simple plugin that lets the user run an alarm at a specified time
or at the end of a specified countdown period.

  * **[[#Screenshots|Screenshots]]**
  * **[[#Latest Release|Latest Release]]**
  * **[[#Source Code Repository|Source Code Repository]]**
  * **[[#Reporting Bugs|Reporting Bugs]]**

----

===== Usage =====
The plugin consists of a Panel icon and a Properties window.

*Panel icon*
The icon displays a progress bar showing the percentage of the time
elapsed. The bar changes color when active from silver to blue.
Left-clicking on the icon opens a menu of available alarms. After selecting
one, the user can start or stop the timer by selecting the "start/stop
timer" entry in the same menu. Right-clicking on it provides access to
Properties.

*Properties window*
The Xfce4 Timer Options window allows users to add, edit, remove and
arrange alarms.

Each alarm is either a countdown or is run at a specified time. By default
a simple dialog pops up at the end of the countdown.

The user can choose an external command to be run as the alarm command for
all events, or for just a particular one. An option allows this command to
be repeated a specified number of times with a given interval between
repetitions. Here is an example that uses a simple ping:
<code>play /usr/share/sounds/freedesktop/stereo/completed.oga</code>
A different external command may be used for a specific event by adding it
in the Alarm add/edit window.

=====Known issues=====
The icon may be nearly invisible against some themes. The colors being used
can be adjusted with a code snippet in the css file. For GTK3, the
following code can be used to adjust inactive ("trough") and active
("progress") colors. For example:
<code>#PLUGIN_NAME progress {
background-color: silver;
}

#PLUGIN_NAME trough {
background-color: red;
} </code>
The actual plugin name, usually something like *xfce4-timer-plugin-2* where
the widget number at the end is particular to individual desktops, can be
found by hovering over its widget on the  Panel Properties > Items tab.
==========
==========
Notes
1) It would be much better to have a default sound file already filled in
so that the timer could be used OOTB
2) The sound file I used as an example (or another that would work without
fuss) could be supplied with the app to make the user's job much easier
3) Not sure you want to include the Known Issue section, but we find that
appearance questions come up pretty frequently with 4.14.

I hope this is of some use--thanks for all you do.

Jerry
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20200607/98309542/attachment.html>