/ 
Tk-DBI-LoginDialog-1.005
River stage zero No dependents
/ Tk::DBI::LoginDialog

NAME

Tk::DBI::LoginDialog - DBI login dialog class for Perl/Tk.

SYNOPSIS

  use Tk::DBI::LoginDialog;

  my $top = new MainWindow;

  my $d = $top->LoginDialog(-dsn => 'XE');
 
  $d->username("scott");	# default a username

  my $dbh = $d->login;

  print $d->error . "\n"
	unless defined($dbh);

  # ... or ...

  $d->Show;

  print $d->error . "\n"
	unless defined($d->dbh);

DESCRIPTION

"Tk::DBI::LoginDialog" is a dialog widget which interacts with the DBI interface specifically to attempt a connection to a database, and thus returns a database handle.

This widget allows the user to enter username and password details into the dialog, and also to select driver, and other driver-specific details where necessary.

The dialog presents three buttons as follows:

Cancel: hides the dialog without further processing or interaction.
Exit: calls the defined exit routine. See CALLBACKS.
Login: attempt to login via DBI with the credentials supplied.

WIDGET-SPECIFIC OPTIONS

LoginDialog provides the following specific options:

-mask

The character or string used to hide (mask) the password.

-pressed

The name of the button pressed during a login sequence.

-retry

The number of times that attempts will be made to login to the database before giving up. A default applies.

CALLBACKS

LoginDialog provides the following callbacks:

-command

Per the DialogBox widget, this maps the Login button to the DBI login routine.

-exit

The sub-routine to call when the Exit button is pressed. Defaults to Tk::exit.

-showcommand

This callback refreshes items in the dialog as part of the Show method.

ADVERTISED WIDGETS

Component subwidgets can be accessed via the Subwidget method. Valid subwidget names are listed below.

Name: driver, Class: BrowseEntry

Widget reference of driver drop-down widget.

Name: dsn, Class: Entry
Name: username, Class: Entry
Name: password, Class: Entry

Widget references for the basic credential entry widgets.

Name: L_driver, Class: Label
Name: L_dsn, Class: Label
Name: L_username, Class: Label
Name: L_password, Class: Label

Widget references of the left-most label widgets.

Name: error, Class: ROText

Widget reference of the status/error message widget.

METHODS

connect(Driver, DSN, Username, Password)

The DBI connection routine. This does not interact with any Tk widgets so can be called natively, if required. This routine is also called when the Login button is pressed. Returns a database handle and a string message indicating status of connection attempt.

dbh

Returns the database handle associated with the current object.

disconnect

Will call the DBI disconnection routine, using the stored handle. This routine is called when the Login button is pressed.

driver [EXPR]

Set or return the driver property. For specific drivers, the label associated with the dsn may also change to better match the nomenclature of the specified database management system.

If a driver is specified which is not currently "available", then this method will re-set the driver to the first available.

drivers [LIST]

Returns a list of available drivers. This defaults to those drivers defined as available by DBI. Note that it is possible to override this list, however this should be done with caution, as it could cause DBI errors during the login process. The most likely use of this method is to constrain the list of drivers to a subset of those available by default.

dsn [EXPR]

Set or return the dsn property. In some drivers this refers to the database name or database instance.

error

Return the latest error message from the DBI framework following an attempt to connect via the specified driver. If last connection attempt was successful, this will return the DBI message "Connected okay."

login [RETRY]

A convenience function to show the login dialog and attempt connection. The number of attempts is prescribed by the RETRY parameter, which is optional. Returns a DBI database handle, subject to the DBI connect method.

password [EXPR]

Set or return the password property. May not be applicable for all driver types.

Show

The Show method behaves as per the DialogBox widget.

username [EXPR]

Set or return the username property. May not be applicable for all driver types.

version [0|1]

Toggle the display of this widget's version number (module version). This can only be done programmatically. The default behaviour is to hide the version. Irrespective of the argument passed, this routine will return the version number.

VERSION

Build V1.005

AUTHOR

Copyright (C) 2014 Tom McMeekin <tmcmeeki@cpan.org>

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

SEE ALSO

perl, DBI, Tk, Tk::DialogBox.