FVWM - Perl library - FVWM::Tracker

Manual page for FVWM::Tracker in unstable branch (2.5.14)

FVWM::Tracker

DESCRIPTION

When a tracker is created it may enter its own event loop to gather an initial data, so the returned tracker object already has the initial data. It also continues to update the data automatically until it is stopped.

This package is a superclass for the concrete tracker implementations. It defines the common Tracker API, including a way to access the tracked data and to define high level events for the tracker caller to observe.  

SYNOPSYS

    my $tracker = $module->track("TrackerName", @params);
    my $initialData = $tracker->data;
    $tracker->observe("observable1", sub { shift->data });
    $tracker->observe("observable2", sub { shift->stop });

In the future this syntax will probably work too:

    my $tracker = new FVWM::Tracker::TrackerName($module, @params);
    my $initialData = $tracker->start;
    $tracker->observe("observable1", sub { shift->data });
    $tracker->observe("observable2", sub { shift->stop });

PUBLIC METHODS

start

Makes the tracker actually work, i.e. listen to fvwm events, gather data and forms high level events, so called observables.

This method is usually automatically called when the tracker is created unless specifically asked not to.

stop

Stops the tracker activity. The corresponding fvwm events are not listened, data is not updated and no observers called.

To return the tracker to the normal activity, call start method.

restart

This is a shortcut method to stop and then start the tracker. The following scenatio is possible. You start the tracker, read its data and immediatelly stop it (to reduce event tracker to the module). At some point you may want to read the updated data, so you restart the tracker and optionally stop it again.

Note that no observers are removed during stop, so the tracker theoretically may be restarted without any side effect even if some observers are defined.

observe [observable] observer-callback

Defines an observer that will be called every time the tracker observable happens. The observer-callback is a CODE reference that gets the following parameters: $module (FVWM::Module object), $tracker (this object), $data (the same as returned by data method) and optional observable parameters that are specific to this observable.

A special observable value ``main'' means the first observable defined in the tracker, it is the default value when no observable is given.

unobserve [observable [observer-id]]

Stops an observing using the observer-id that is returned by observe method.

A special observable value ``main'' means the first observable defined in the tracker. A special observable value ``*'' means all defined observables.

data

Returns the whole data collected by the tracker.

Usually subclasses add an optional parameter key that limits the whole data to the given key.

dump

Returns the string representing the whole tracker data in the human readable form, useful for debugging.

Usually subclasses add an optional parameter key that limits the whole data to the given key.

METHODS FOR SUBCLASSES

observables

A subclass should define a list of observables that a caller may listen to using observe method. It is the subclass responsiblity to actually signal every observable listed using notify method.

Returns a reference to a string array.

new module param-hash

This superclass method should be called by subclasses. Please do not use this class method in programs, use the first syntax shown in the SYNOPSYS section instead.

module is an FVWM::Module instance. param-hash is specific to the concrete Tracker class.

addHandler type handler

A wrapper to FVWM::Module::addHandler, has the same syntax, but stores all handlers so they may be deleted at once using deleteHandlers.

deleteHandlers [handler-ids]

Deletes all handlers defined using addHandler or the ones specified using an optional handler-ids array ref.

notify observable [observable-params]

Notifies all listeners that were defined using observe, by calling their observer function with the following parameters: $module, $tracker, $data, observable-params.

requestWindowListEvents

Subclasses that work using fvwm events sent in responce to Send_WindowList command should call this shortcut method. Automatically sends the needed command (after the tracker event mask is counted) and defines a handler that terminates the initial tracker event loop in response to M_END_WINDOWLIST event.

requestConfigInfoEvents

Subclasses that work using fvwm events sent in responce to Send_ConfigInfo command should call this shortcut method. Automatically sends the needed command (after a tracker event mask is counted) and defines a handler that terminates the initial tracker event loop in response to M_END_CONFIG_INFO event.

internalDie

Subclasses may call this method when something wrong happens. This is a wrapper to FVWM::Module::internalDie.

toBeDisconnected

Does nothing by default. Subclasses may implement this method if something should be sent to fvwm just before the module disconnects itself.

AUTHOR

SEE ALSO

Index

DESCRIPTION

SYNOPSYS

PUBLIC METHODS

METHODS FOR SUBCLASSES

AUTHOR

SEE ALSO

Switch to window theme, pager on top theme, navigation theme,

Last modified on April 26, 2010