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.
- Exit: calls the defined exit routine. See CALLBACKS.
- Login: attempt to login via DBI with the credentials supplied.
These button labels may be overridden using the -buttons and -default_button arguments (refer to the Tk::DialogBox widget for detail).
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.007
AUTHOR
Copyright (C) 2014-2016 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, Log::Log4perl, Tk, Tk::DialogBox.