NAME

Tk::LockDisplay - Create modal dialog and wait for a password response.

SYNOPSIS

$lock = $parent->LockDisplay(-option => value, ... );

DESCRIPTION

This widget fills the display with a screensaver-like animation, makes a global grab and then waits for the user's authentication string, usually their password. Until the password is entered the display cannot be used: window manager commands are ignored, etcetera. Note, X server requests are not blocked.

Password verification is perforemd via a callback passed during widget creation.

While waiting for the user to respond, LockDisplay sets a global grab. This prevents the user from interacting with any application in any way except to type characters in the LockDisplay entry box. See the Lock() method.

The following option/value pairs are supported:

-authenticate

Password verification subroutine - it's passed two positional parameters, the username and password, and should return 1 if success, else 0.

-animation

A string indicating what screensaver plugin to use, or 'none' to disable the screensaver. Supplied plugins are 'lines' (default), 'neko' and 'counter', which reside in the directory .../Tk/LockDisplay. You can drop a plugin of your own in that directory - see the section Plugin Format below for details. You can also supply your own animation subroutine by passing a CODE reference. The subroutine is passed a single parameter, the canvas widget reference, which you can draw upon as you please.

-animationinterval

The number of milliseconds between calls to the screen saver animation code. Default is 200 milliseconds. Plugins can specifiy their own interval by returning the number of milliseconds (> 1) during initialization.

-hide

How many seconds of display inactivity before hiding the password entry widget and canvas title text. Default is 10 seconds.

-text

Title text centered in canvas.

-foreground

Title text color.

-background

Canvas color.

-debug

Set to 1 allows a <Double-1> event to unlock the display. Used while debugging your authentication callback or plugin.

METHODS

$lock->Lock;

This method locks the display and waits for the user's authentication data.

EXAMPLE

$lock = $mw->LockDisplay(-authenticate => \&check_pw);

sub check_pw {

    # Perform AFS validation unless on Win32.

    my($user, $pw) = @_;

    if ($^O eq 'MSWin32') {
	($pw eq $^O) ? exit(0) : return(0);
    } else {
	system "/usr/afsws/bin/klog $user " . quotemeta($pw) . " 2> /dev/null";
	($? == 0) ? exit(0) : return(0);
    }

} # end check_pw

PLUGIN FORMAT

Refer to the "counter" plugin file .../Tk/LockDisplay/counter.pm for details on the structure of a LockDisplay animation plugin. Basically, you create a ".pm" file that describes your plugin, "counter.pm" for instance. This file must contain a subroutine called Animate($canvas), where $canvas is the canvas widget reference passed to it.

LockDisplay first require()s your plugin file, and, if that succeeds, calls it once to perform initialization. Animate() should return 0 for failure, 1 for success, and > 1 for success and to specifiy a private -animationinterval (in milliseconds). Subsequent calls to Animate() are for its "main loop" processing. As before, the return code should be 0 or 1 for failure or success, respectively.

HISTORY

Version 1.0

Beta Release.

Version 1.1

. Implement plugins and other fixes suggested by Achim Bohnet.
  Thanks!
. Allow plugin name 'none' to disable screensaver.  Thanks to
  Roderick Anderson!

Version 1.2

. getlogin() fails on HPUX, so try getpwuid() as a fallback.
  Thanks to Paul Schinder for the CPAN-Testers bug report.
. Plugins can return() their own -animationinterval value 
  during preset.
. Add 'neko' plugin.

Version 1.3

. Fix value of pi in neko plugin!
. Add Windows 95 support

AUTHOR

Stephen.O.Lidie@Lehigh.EDU

COPYRIGHT

Copyright (C) 1998 - 1998, Stephen O. Lidie.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

KEYWORDS

screeensaver, dialog, modal