Class dApp

Specifies the form class to use for the application's About screen.

Returns the form that currently has focus, or None.  (dForm)

Read-only object reference to the Dabo Application object.  (dApp).

Specifies whether .cnxml connection files are automatically imported. (Default True)

The base Dabo class of the object. Read-only.  (class)

Base key used when saving/restoring preferences. This differs
from the default definition of this property in that if it is empty, it
will return the ActiveForm's BasePrefKey or the MainForm's BasePrefKey
in that order. (str)

The class the object is based on. Read-only.  (class)

Reference to the object that provides cryptographic services.  (varies)

When set, creates a DES crypto object if PyCrypto is installed. Note that
each time this property is set, a new PyCrypto instance is created, and
any previous crypto objects are released. Write-only.  (varies)

The form class to open by default, automatically, after app instantiation.  (form class reference)

The class used by all forms in the application when no specific MenuBarClass
is specified  (dabo.ui.dMenuBar)

Determines if sizer outlines are drawn on the ActiveForm.  (bool)

Name of encoding to use for unicode  (str)

List of forms to open after App instantiation.  (list of form class references)

Specifies the application's home directory. (string)

The HomeDirectory is the top-level directory for your application files,
the directory where your main script lives. You never know what the
current directory will be on a given system, but HomeDirectory will always
get you to your files.

Specifies the icon to use on all forms and dialogs by default.

The value passed can be a binary icon bitmap, a filename, or a
sequence of filenames. Providing a sequence of filenames pointing to
icons at expected dimensions like 16, 22, and 32 px means that the
system will not have to scale the icon, resulting in a much better
appearance.

Specifies which events to log.  (list of strings)

If the first element is 'All', all events except the following listed events
will be logged.
Event logging is resource-intensive, so in addition to setting this LogEvents
property, you also need to make the following call:

	>>> dabo.eventLogging = True

The class to use for logging in.

The object reference to the main form of the application, or None.

The MainForm gets instantiated automatically during application setup,
based on the value of MainFormClass. If you want to swap in your own
MainForm instance, do it after setup() but before start(), as in::

>>> import dabo
>>> app = dabo.dApp()
>>> app.setup()
>>> app.MainForm = myMainFormInstance
>>> app.start()

Specifies the class to instantiate for the main form. Can be a
class reference, or the path to a .cdxml file.

Defaults to the dFormMain base class. Set to None if you don't want a
main form, or set to your own main form class. Do this before calling
dApp.start(), as in::

>>> import dabo
>>> app = dabo.dApp()
>>> app.MainFormClass = MyMainFormClass
>>> app.start()

The name of the object.  (str)

Text to display for null (None) values.  (str)

The containing object.  (obj)

Returns the platform we are running on. This will be
one of 'Mac', 'Win' or 'GTK'.  (str)

Specifies the dialog to use for the application's user preferences.

If None, the application will try to run the active form's onEditPreferences()
method, if any. Otherwise, the preference dialog will be instantiated and
shown when the user chooses to see the preferences.

Reference to the Preference Management object  (dPref)

If False, the preference dialog will remain hidden in memory after closed,
resulting in better performance when bringing up the dialog more than once.

Note that you'll still have to handle intercepting your dialog's Close event and
hiding it instead of releasing, or you'll be battling dead object errors.

Specifies the delay before incrementeal searching begins.  (int)

As the user types, the search string is modified. If the time between
keystrokes exceeds SearchDelay (milliseconds), the search will run and
the search string	will be cleared.

The value set here in the Application object will become the default for
all objects that provide incremental searching application-wide.

Specifies the Security Manager, if any.

You must subclass dSecurityManager, overriding the appropriate hooks
and properties, and then set dApp.SecurityManager to an instance of your
subclass. There is no security manager by default - you explicitly set
this to use Dabo security.

Specifies whether the command window option is shown in the menu.

If True (the default), there will be a File|Command Window option
available in the base menu. If False, your code can still start the
command window by calling app.showCommandWindow() directly.

Specifies whether the "Show Sizer Lines" option is shown in the menu.

If True (the default), there will be a View|Show Sizer Lines option
available in the base menu.

If this app's source files are updated dynamically via the web,
this is the base URL to which the source file's name will be appended.
Default="" (i.e., no source on the internet).  (str)

Specifies the user interface to load, or None. (str)

This is the user interface library, such as 'wx' or 'tk'. Note that
'wx' is the only supported user interface library at this point.

The name of the ui-specific app subclass to instantiate.

This will allow ui toolkit-specific behaviors to be added to a Dabo
application. It MUST be either defined in the application subclass, or
passed in the call to create the app object, since the UI App cannot
be changed once the app is running. Defaults to dabo.ui.uiApp
if not specified.  (dabo.ui.uiApp)

Specifies the reference to the object providing user preference persistence.

The default UserSettingProvider will save user preferences inside the .dabo
directory inside the user's home directory.

Specifies the class to use for user preference persistence.

The default UserSettingProviderClass will save user preferences inside the .dabo
directory inside the user's home directory, and will be instantiated by Dabo
automatically.

Occurs when the form or application becomes active.

Occurs when another form becomes active.

Occurs when a key is depressed and released on the
focused control or form.

Occurs when any key is depressed on the focused control or form.

Occurs when any key is released on the focused control or form.

Accepts a cnxml file path, and reads in the connections
defined in it, adding them to self.dbConnectionDefs. If the
file cannot be found, an exception is raised.

Adds additional app-specific information to the About form.
This is just a stub method; override in subclasses if needed.

Stub method. When this is called, the app has already terminated, and you have
one last chance to execute code by overriding this method.

Subclass hook. Called after the object's __init__ has run fully.
Subclasses should place their __init__ code here in this hook, instead of
overriding __init__ directly, to avoid conflicting with base Dabo behavior.

Hook method that is called after the app's setup code has run, and the
database, UI and module references have all been established.

Automatically bind any on*() methods to the associated event.

User code only needs to define the callback, and Dabo will automatically
set up the event binding. This will satisfy lots of common cases where
you want an object or its parent to respond to the object's events.

To use this feature, just define a method on<EventName>(), or	if you
want a parent container to respond to the event, make a method in the
parent on<EventName>_<object Name or RegID>().

For example::
	
	class MyButton(dabo.ui.dButton):
		def onHit(self, evt):
			print "Hit!"

	class MyPanel(dabo.ui.dPanel):
		def afterInit(self):
			self.addObject(MyButton, RegID="btn1")

		def onHit_btn1(self, evt):
			print "panel: button hit!"

When the button is pressed, you'll see both 'hit' messages because of
auto event binding.

If you want to bind your events explicitly, you can turn off auto event
binding by calling::

	 dabo.autoBindEvents = False

This feature is inspired by PythonCard.

Subclass hook. Called before the object is fully instantiated.
Usually, user code should override afterInit() instead, but there may be
cases where you need to set an attribute before the init stage is fully
underway.

Bind a dEvent to a callback function.

Bind a sequence of [dEvent, callback] lists.

Public interface to the web updates mechanism. Returns a boolean
indicating whether the update was successful.

Called by the form when it is deactivated.

Cleanup as the app is exiting.

Place the passed text onto the clipboard.

Return decrypted string value. The request is passed to
the Crypto object for processing.

Deletes all settings that begin with the supplied spec.

Removes the given item from the user settings file.

Displays a messagebox dialog along with a checkbox for the user
to specify whether or not to show this particular message again
in the future.

If user unchecks "show in future", saves that to the user's
preference file and future calls to this function with that
msgId will result in no message being shown.

Return the encrypted string value. The request is passed
to the Crypto object for processing.

Called when the application event loop has ended. You may also
call this explicitly to exit the application event loop.

Increase the font size on the active form.

Reset the font size to normal on the active form.

Decrease the font size on the active form.

Return the fully qualified name of the object.

Look up the item, and return the value.

Returns one of 'unicode' or 'ascii'.

Given the name of a connection, returns the actual
connection. Stores the connection so that multiple requests
for the same named connection will not open multiple
connections. If the name doesn't exist in self.dbConnectionDefs,
then an exception is raised.

Returns a list of all defined connection names

Given an absolute path to a .cnxml file, return the connection defs.

Return a tuple of (user, password) to dSecurityManager.login(). The default
is to display the standard login dialog, and return the user/password as
entered by the user, but subclasses can override to get the information from
where ever is appropriate. You can customize the default dialog by adding
your own code to the loginDialogHook() method, which will receive a
reference to the login dialog.

Return a tuple of (user, pass).

Returns a dictionary of property name/value pairs.

If a sequence of properties is passed, just those property values
will be returned. Otherwise, all property values will be returned.
The sequence of properties can be a list, tuple, or plain string
positional arguments. For instance, all of the following are
equivilent::

	print self.getProperties("Caption", "FontInfo", "Form")
	print self.getProperties(["Caption", "FontInfo", "Form"])
	t = ("Caption", "FontInfo", "Form")
	print self.getProperties(t)
	print self.getProperties(\*t)

An exception will be raised if any passed property names don't
exist, aren't actual properties, or are not readable (do not have
getter functions).

However, if an exception is raised from the property getter function,
the exception will get caught and used as the property value in the
returned property dictionary. This allows the property list to be
returned even if some properties can't be evaluated correctly by the
object yet.

Return the path to one of the standard Dabo application directories.
If a starting file path is provided, use that first. If not, use the
HomeDirectory as the starting point.

Return a tuple of the fullpath to each standard directory

Only one bizobj at a time can begin and end transactions per connection.
This allows the bizobj to query the app for the 'token', which is simply an
acknowledgement that there is no other transaction pending for that connection.
If the bizobj gets the token, further requests for the token from bizobjs using the
same transaction will receive a reply of False, meaning that they should not be
handling the transaction.

Return the full name of the currently logged-on user.

Return the value of the item in the user settings table.

Return a list of all keys underneath <spec> in the user settings table.

For example, if spec is "appWizard.dbDefaults", and there are
userSettings entries for:
	
	appWizard.dbDefaults.pkm.Host
	appWizard.dbDefaults.pkm.User
	appWizard.dbDefaults.egl.Host

The return value would be ["pkm", "egl"]

Returns a 2-tuple that reflects the current settings for web updates.
The first position is a boolean that reflects whether auto-checking is turned
on; the second is the update frequency in minutes.

Returns True/False, depending on whether the specified
bizobj currently "holds" the transaction token.

Hook for subclasses. User code should do custom event binding
here, such as::
	
	self.bindEvent(dEvents.GotFocus, self.customGotFocusHandler)
	

Hook for subclasses. User subclasses should set properties
here, such as::
	
	self.Name = "MyTextBox"
	self.BackColor = (192,192,192)
	

Callback from the initial app setup. Used to allow the
splash screen, if any, to be shown quickly.

Hook method; modify the dialog as needed.

Send the event to all registered listeners.

If uiEvent is sent, dEvents.Event will be able to parse it for useful
information to send along to the callback. 

Additional arguments, if any, are sent along to the constructor	of the
event. While this feature exists so that UI-lib event handlers can pass
along information (such as the keystroke information in a key event), user
code may pass along additional arguments as well, which	will exist in the
event.EventData dictionary property.

In most cases, user code should call raiseEvent() with
the event class (dEvents.Hit, for example) as the only parameter.

When a process that would normally close a transaction happens, the
bizobj that is holding the transaction token for its connection calls this
method to return the token. A check is run to ensure that the releasing bizobj
is the one currently holding the token for its connection; if it is, the item is
removed from the _transactionTokens dict.

In the middle of an app's lifetime, files on the remote server may
have been updated. This will ensure that the local copy is in sync.

Set item to value in the appinfo table.

Allows you to change the language used for localization. If the language
passed is not one for which there is a translation file, an IOError exception
will be raised. You may optionally pass a character set to use.

Sets a group of properties on the object all at once.

You have the following options for sending the properties:
	
	1) Property/Value pair dictionary
	2) Keyword arguments
	3) Both

The following examples all do the same thing::

	self.setProperties(FontBold=True, ForeColor="Red")
	self.setProperties({"FontBold": True, "ForeColor": "Red"})
	self.setProperties({"FontBold": True}, ForeColor="Red")

Sets a group of properties on the object all at once. This
is different from the regular setProperties() method because
it only accepts a dict containing prop:value pairs, and it
assumes that the value is always a string. It will convert
the value to the correct type for the property, and then set
the property to that converted value. If the value needs to be evaluated
in a specific namespace, pass that as the 'context' parameter.

Persist a value to the user settings file.

Convenience method for setting several settings with one
call. Pass a dict containing {settingName: settingValue} pairs.

Set up the application object.

Shows a command window with a full Python interpreter.

This is great for debugging during development, but you should turn off
app.ShowCommandWindowMenu in production, perhaps leaving backdoor
access to this function.

The context argument tells dShellForm what object becomes 'self'. If not
passed, context will be app.ActiveForm.

Start the application event loop.

Open one or more of the defined forms. The default one is specified
in self.DefaultForm. If form names were passed on the command line,
they will be opened instead of the default one as long as they exist.

Shows/hodes a debug output window. It will
display the output of the debugging commands
from your program.

Remove a previously registered event binding.

Removes all registrations that exist for the given binding for this
object. If event is None, all bindings for the passed function are
removed. If function is None, all bindings for the passed event are
removed. If both event and function are None, all event bindings are
removed.

This method takes either a single file path or a list of paths, and if there
is a SourceURL set, checks the source to see if there are newer versions available,
and if so, downloads them.

Fetches the specified resource from the internet using the SourceURL value
as the base for the resource URL. If a newer version is found, the local copy
is updated with the retrieved resource. If the resource isn't found, nothing
happens by default. If you want the error to be raised, pass True for the
parameter 'errorOnNotFound'.