# declare our package:
        package PerlPanel::Applet::HelloWorld;

        # constructor:
        sub new {
                my $self                = {};
                $self->{package}        = shift;
                bless($self, $self->{package});
                return $self;
        }

        # build the widget:
        sub configure {
                my $self = shift;
                $self->{widget} = Gtk2::Button->new('Click Me!');
                $self->widget->signal_connect(
                        'clicked',
                        sub {
                                PerlPanel::alert(
                                        'Hello World!'
                                );
                        }
                );
                $self->widget->show_all;
        }

        # return the widget;
        sub widget {
                return $_[0]->{widget};
        }

        # return the expand (1 or 0) for packing:
        sub expand {
                return 0;
        }

        # return the fill (1 or 0) for packing:
        sub fill {
                return 0;
        }

        # return 'start' or 'end':
        sub end {
                return 'start';
        }

        sub get_default_config {
                my $hashref = {
                        name    => 'value',
                        'foo'   => 'bar',
                        'list'  => [1, 2, 3, 4, 5],
                };
                return $hashref;
        }

        1;

INTRODUCTION

The package name for the applet must be of the form

        PerlPanel::Applet::AppletName

and should have the filename

        AppletName.pm

In order to work properly with the PerlPanel, they need to have an interface the PerlPanel can understand.

When it loads a module, PerlPanel will create a new instance of the applet. It will then call various methods of the object in order to work out what to do with it.

These methods are explained below.

APPLET TYPES

Multi applets are different. A multi applet can appear several times on the panel, and each instance can have its own configuration settings.

CREATING A MULTI APPLET

        $MULTI = 1;

The value of $MULTI must be a true value (1 is the simplest).

When PerlPanel loads the applet, it checks the value of this variable and if it's true, then it supplies an ID argument to the applet constructor. See below for details.

Finally, when you are querying for a configuration hashref, you must supply the ID mentioned above in your call to "PerlPanel::get_config()". See below for more details.

REQUIRED METHODS

        $applet->new

The constructor. The arguments supplied to the constructor vary, depending on whether the applet has been defined as a multi applet or not.

If the $MULTI variable has not been set, then @_ will look like this:

        @_ = ($package);

where $package is a scalar containing the package name of the applet, eg "PerlPanel::Applet:FooBar". If the $MULTI variable is true, then @_ will look like this:

        @_ = ($package, $id);

where $id is a scalar containing the ID of the instance. You must store this ID and use it when you request config data.

        $applet->configure

This stage is intended for the loading of config data, creation of widgets, etc.

        $applet->widget

This method should return the Gtk widget that is to be displayed on the panel. It can be any kind of Gtk widget apart from a window.

        $applet->expand
        $applet->fill

The panel uses a horizontal packing box to contain the applet widgets. These two methods return integer values for the 'expand' and 'fill' arguments to "pack_start()".

        $applet->get_default_config

This method returns a reference to a hash containing the default configuration data. This data is imported into the user's config file and is saved to disk and can then be modified by the user as needed. It is only called once - the first time the applet is loaded, after which the panel will use the data from the user's config file.

If this methods returns "undef" then the panel will assume there is no configuration data.

NB: The "end()" function is now deprecated and does not need to be used in new applets.

HISTORICAL NOTE

        $PerlPanel::OBJECT_REF->function_name

As of version 0.4.0, the syntax is

        PerlPanel::function_name

Compatibility with the old syntax was removed in version 0.7.0.

USEFUL VARIABLES

        $PerlPanel::OBJECT_REF

This is a reference to the main panel object. A number of methods are available for your use, they're explained below.

        @PerlPanel::APPLET_DIRS

This contains directory paths which PerlPanel will use to search for applets. It will at least contain "$PREFIX/lib/perlpanel/PerlPanel/Applet" and "$HOME/.perlpanel/applets".

USEFUL FUNCTIONS

        PerlPanel::get_config($appletname, [$id])

This function returns a reference containing the configuration data for the applet. The structure of the data will be that defined by the "get_default_config" function.

If you supply the second $id argument, then the function will return the appropriate config data for the instance of the applet defined by $id.

        PerlPanel::tips()

This returns a "Gtk2::Tooltips" object ready for use. In versions prior to 0.4.0, this was accessed using $PerlPanel::TOOLTIPS_REF.

        PerlPanel::icon()

This returns a GdkPixbuf object containing the PerlPanel icon. You should use this pixbuf to set the icon for any windows you create, eg:

        $dialog->set_icon(PerlPanel::icon);

You don't need to resize the pixbuf, this is done when the application (a window manager, or task list) requires it.

        PerlPanel::icon_size()

The size of icons on the panel, in pixels. You should use this to scale things so that everything fits nicely together.

        PerlPanel::screen_width

        PerlPanel::screen_height

        $translated = _($original, %params);

$original is the original, presumably English, string. Any occurances of the keys of %params are replaced with their values, for example:

        $translated = _(
                "there are {number} {type} {object}",
                number  => 6,
                type    => 'red',
                object  => 'apples'
        );

Applet authors are encouraged to wrap all the strings they use in their applets in "_()".

WRITING MENU APPLETS

MANAGING TIMEOUTS

PerlPanel has a system to track timeouts created by applets, and to remove them when the panel is reloaded, or when a particular applet is removed from the panel. Instead of using "Glib::Timeout->add($msec, $callback)" to set up your applet, use the following function:

        $id = PerlPanel::add_timeout($msec, $callback);

The arguments and return values for this function are identical to those of "Glib::Timeout->add()". When the panel is reloaded, all the applets are removed and new ones are created, so the panel will automatically clean up these timeouts.

When you want to cancel a timeout, use this function:

        PerlPanel::remove_timeout($id);

When the code in $callback is executed, it will receive a reference to a scalar containing the ID as the first member of @_. So if you want to cancel the timeout from within the callback, you can call write like this:

        PerlPanel::remove_timeout(${shift()});

PACKAGING YOUR APPLET

        /
        /applet.info
        /applets
        /applets/AppletName.pm
        /share
        /share/icons
        /share/icons/hicolor
        /share/icons/hicolor/48x48
        /share/icons/hicolor/48x48/apps
        /share/icons/hicolor/48x48/apps/perlpanel-applet-appletname.png
        /share/icons/hicolor/48x48/apps/perlpanel-applet-appletname-action-specific-icon.png
        /share/perlpanel
        /share/perlpanel/glade
        /share/perlpanel/glade/appletname.glade

The "applet.info" file should contain a single line of the form:

        AppletName:A short description of what your applet does.:Category

This line is appended to the user's applet.registry, so they see a descriptive entry in the Add Applet dialog. The first field must match the "AppletName" part of the tarball's name.

The $Version part of the file name should contain only digits and periods. Valid version strings include: 1.00 (Perl style), 1.0.0 (Kernel style), and so on.

The .pm file which contains your applet should go into "applets/". The installer will look for a file called "AppletName.pm", where "AppletName" is taken from the "AppletName" part of the tarball's name. PerlPanel will place this file into "$HOME/.perlpanel/applets".

The files inside the "share/" subdirectory are installed into "$HOME/.local/share". This is a directory defined by the Freedesktop.org base directory specification as the place in which user specific data files should be stored. You can use this subdirectory to install Glade files (which can be accessed using "load_glade()" - see above), your applet's icon, and any supporting icons you may need. Using this path means that calls to "lookup_icon" will work out the same as if the icons were in "$PREFIX/share/icons", and can also be themed.

For example, if your applet controls a media player, and you want to include icons for the Previous, Forward, Play and Pause buttons, you can include these icons like this:

        /share/icons/hicolor/48x48/apps/perlpanel-applet-mediaplayer-previous.png
        /share/icons/hicolor/48x48/apps/perlpanel-applet-mediaplayer-next.png
        /share/icons/hicolor/48x48/apps/perlpanel-applet-mediaplayer-play.png
        /share/icons/hicolor/48x48/apps/perlpanel-applet-mediaplayer-pause.png
        /share/icons/hicolor/48x48/apps/perlpanel-applet-mediaplayer-stop.png

And then in your applet code, you can retrieve these icons by using this:

        my $pbf = PerlPanel::lookup_icon('mediaplayer-previous', PerlPanel::icon_size);

FURTHER CONSIDERATIONS

For example, this is very bad:

        my $executable = '/usr/bin/executable';

If the user doesn't have the "executable" program, they may install it from source, in which case it will probably end up in "/usr/local/bin", and your applet will break for no reason.

A much better solution is to do this:

        chomp(my $executable = `which executable 2>/dev/null`);
        if (!-x $executable) {
                PerlPanel::warning(_('Cannot find the {program} program!', program => 'executable'));
        }

This will allow "executable" to be anywhere in the user's path, and will alert the user if there was a problem.

Another area where this can cause problems is the use of external shared files, such as graphics and icons. Wherever possible, package shared files in your tarball as shown in ``PACKAGING YOUR APPLET''.