Application

From Xojo Documentation

Revision as of 18:52, 19 November 2009 by WikiSysop (talk) (Properties)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Description

Includes properties, methods, and events for managing the application as a whole. In the IDE, the Properties pane for the App class includes numerous pseudo-properties that are described in the section "Customizing the Standalone Application's Properties" on page 694 of the User's Guide.


Super Class

Object

Events

Name Parameters Return Type Description
Activate The application is being activated.

When the application is launched, the Open event fires prior to Activate.

CancelClose
Changed 2005r1
Boolean This event occurs when the application is about to terminate.

It occurs prior to all of the CancelClose events for each Window. It gives you the chance to cancel the application's termination. Returns a Boolean. Return True to cause the termination to stop.

Close The application is quitting. Close is called after CancelClose and after the windows' CancelClose and Close events.
Deactivate The application is being deactivated.

For example, this occurs when the user clicks on a window belonging to another application. When the user clicks on a REALbasic application window again, the Activate event fires.

EnableMenuItems Executes when the user clicks in the menubar to give you the opportunity to determine which menu items to enable.

It also executes when the application opens if no default window is selected in the Project Settings dialog box and when the last window is closed.

HandleAppleEvent Event as AppleEvent
EventClass as String,
EventID as String
Boolean An AppleEvent has been received.

Return True to accept the AppleEvent and False to reject it. Intrinsic AppleEvents, such as "odoc", "quit", and "pref", are passed to this event handler first. If you return True, the default behavior will no longer take place. For example, if you return True for the "odoc" event, the OpenDocument event will not fire.

NewDocument The user launched the application by double-clicking the application icon or the NewDocument method was called.
Open The application is opening.

The Activate event fires after the Open event.

OpenDocument File as FolderItem The user has double-clicked on a document whose creator matches the application's creator or the OpenDocument method was called.
UnhandledException error as RuntimeException Boolean Receives otherwise missed exceptions-exceptions that could have been caught in an Exception statement using one of the Runtime exception handlers.

If the appropriate Exception statement is missing, the runtime exception error triggers this event and allows you to handle exceptions here. See the example. Returns a Boolean. If it returns True, the standard alert indicating an unhandled exception and quit behavior are suppressed. Return False to allow REALbasic's default unhandled exception error processing to occur. See the RuntimeException class.

Properties

Name Type Description
AcceptFileTypes
Introduced 2005r1
String Specifies which file types the application will accept via drag and drop.

Applies only to the initial or "blessed" instance based on the Application class and is for Macintosh only. Use the File Type Sets Editor to enter the file types and in the App object's Properties pane, click the "..." button to open a dialog box in which you can edit this list.

AutoQuit
Introduced 5.5
Boolean If True, the application will quit when the last window is closed, whether by calling the Close method of the Window class or the user closed the last window.

AutoQuit defaults to True on non-MDI Windows applications and True on Linux. It defaults to False on MDI Windows and Macintosh applications.

BugVersion
Integer The Bug version of the application.
BuildDate
Introduced 2005
Date Contains the date and time when the application was built.

You can also access the CreationDate property of the application's FolderItem by calling app.executableFile.CreationDate

CurrentThread
Introduced 2005r1
Thread Obtains the currently running Thread.

If the current Thread is the main thread (the thread that REALbasic creates and manages itself to run the application), CurrentThread returns Nil.

DockItem
Introduced 5.0
DockItem Enables you to manipulate the dock item associated with the application (Mac OS X only).

The DockItem property enables you to access the properties and methods of the DockItem class. This class has two methods, UpdateNow and ResetIcon, and one property, Graphics. Use the methods of the Graphics class to modify the appearance of the icon. Since a Mac OS X icon is intended to be scaled automatically, you should design it as a 128x128 pixel icon. ResetIcon resets the icon to its original state (default appearance). Call the UpdateNow method to redraw the icon. You can also use the ClearRect property of the Graphics class to start over from a blank icon. Anything you can do with a Graphics object you are able to do with the Dock's Graphics object (like drawing in a picture or using a Group2D). The DockItem property of the Window class enables you to control the dock item for individual windows.

ExecutableFile
Introduced 5.5
FolderItem Returns a FolderItem for the actual executable application even if it is in a bundle.

Use the properties and methods of the FolderItem class to get/set attributes of the executable file and/or perform operations. For example: app.ExecutableFile.AbsolutePath gets the full path to the executable. app.ExecutableFile.CreationDate gets the date/time the executable was created.

LongVersion String Long version of the application, corresponding to the version information.
MajorVersion
Integer Major version of the application, corresponding to the version information. The range is from 0 to 255.
MDIWindow MDIWindow Provides access to the properties and methods of the MDIWindow class.

Valid only for Windows applications that are built using the Multiple Document Interface option.

MenuBar
Introduced 5.0
MenuItem Represents the application's global menubar. Its children are the menus.

You can replace the entire menubar by assigning a new MenuItem to MenuBar. Each Window can have a menubar assigned to it via its MenuBar property. If no menubar is assigned to the window, the application's menubar is used.

MinorVersion
Integer Minor version of the application, corresponding to the version information. The range is from 0 to 255.
MouseCursor MouseCursor The cursor that is displayed while the application is running and the pointer is within one of the application's windows.

On Macintosh, it is also the cursor that is displayed when the application is frontmost and the pointer moves outside of any of the application's windows. On Windows and Linux, the pointer changes back to the default pointer when it exits an application window. If the Application class MouseCursor is not Nil, the non-Nil MouseCursor properties belonging to any Windows or Controls are ignored. You can use the cursors in the Cursors module to set the mousecursor.

NonReleaseVersion
Integer The NonRelease version of the application, corresponding to the version information.
PackageInfo String The Package Info of the application, corresponding to the version information.
RegionCode
Integer The Region Code of the application, corresponding to the version information. Not supported on Windows.
ResourceFork
ResourceFork Used to access the application's resources.

Supported only on Macintosh. Check the value of TargetMacOS before attempting to access the application's resources.

ShortVersion String Short version of the application, corresponding to the version information.
StageCode
Changed 2005r1
Integer Stage Code of the application, corresponding to the version information.

Use the four Application class constants to determine the Stage: 0 - Development 1 - Alpha 2 - Beta 3 - Final

UseGDIPlus
Introduced 2009r4
Boolean If True, the Graphics class on Windows will use GDI+ to do its drawing. The default is False.

Methods

Name Parameters Return Type Description
AddTrayItem
Introduced 2005r1
Item as TrayItem Boolean
Introduced 2009r4
Adds the passed item to the System Tray via the TrayItem class.

AddTrayItem returns a Boolean that indicates successor failure. If it returns True, the TrayItem was added successfully. The System Tray is supported on Windows and Linux only. See the TrayItem class for an example.

DoEvents
Introduced 5.5
[milliseconds as Integer] Yields time back to REALbasic in loops. Intended for console applications in which there is no main event loop.

You can call DoEvents in the Run event in a console application to create your own main event loop. However, using DoEvents in a GUI application will likely cause instability. In effect, you would be placing a main event loop inside the 'real' main event loop. You should consider using threads to handle lengthy operations rather than placing them in the main thread and calling DoEvents to maintain the interface. If the current method is running inside a Thread, DoEvents will yield to the main thread instead of running one iteration of the event loop inside the thread, causing confusion. If you use DoEvents inside a loop, the you cannot use the UserCancelled function to detect whether the user pressed the Esc key (Windows or Linux) or Command-period (on Macintosh) to break out of the loop. Since DoEvents keeps the user interface responsive while the loop is running, you can add a button to the user interface that the user can click to stop the loop. The optional parameter specifies the amount of time you want the currently executing thread to sleep. DoEvents can cause a Thread to sleep with a resolution greater than 16 milliseconds. If all threads are sleeping, then REALbasic yields back time to the system. This allows you to write applications that don't use up to 100% of the CPU during tight loops. Specifying zero milliseconds causes the next waiting thread to execute. A negative value specifies no sleep. The default is -1.

NewDocument Calls the NewDocument event handler.
OpenDocument File as FolderItem Calls the OpenDocument event handler.
RemoveTrayItem
Introduced 2005r1
Item as TrayItem Removes the passed item from the System Tray via the TrayItem class.

The System Tray is supported on Windows and Linux only. See the TrayItem class for an example.

SleepCurrentThread
Introduced 2005r1
Milliseconds as Integer Sleeps the current thread for the specified number of milliseconds. It can be used for any thread.
YieldToNextThread
Introduced 2005r1
Triggers a context change.

It causes the Thread Scheduler to yield the currently executing thread's processing time to the next Thread in the queue that is awaiting processing cycles. It is possible for the next Thread to be the currently executing Thread.


Class Constants

The following class constants can be used to specify the value of the StageCode property.

Constant Value
Development 0
Alpha 1
Beta 2
Final 3


Notes

REALbasic adds a class based on the Application class to the Project Editor when you create a new Desktop Application project. This new subclass will give you access to the Application object's methods and events. If you created a Console Application, the App class's Super class is ConsoleApplication, not Application.

If you wish, you can add additional subclasses based on the Application class to the project, but it is not necessary. If you do so, the one that is added to the project automatically is the one referred to by the App function and it is the one that will show the project's build settings.

The new subclass has its own menu handlers which can be used to handle menu items when no windows are open or for menu items that should call the same menu handler regardless of which window is frontmost. You can change the global menubar by assigning a different menubar to its MenuBar property.

See the Control class for information on changing the cursor and adding cursors to your project.

The App function returns a reference to the Application object. See the App function for more information.

Resource files (files of type "rsrc") created with a resource editor can be added to your project adding each resource file to the Project. These resources are then accessible through the Application object's ResourceFork property. The resources from all your resource files will be copied into the built Macintosh application. In the case of a conflict, later resource files overwrite earlier ones, where the files are written in the order in which they appear in the Project Editor.

The application resources are read-only. If you need to write to resources you will need to use an external resource file. See the ResourceFork class for more information.

Note: Access to the resourcefork is supported only on Macintosh. Check the value of the TargetMacOS constant before attempting to access the application's resourcefork.


Version Information

The compiler autoincrements version information for a project on each compile.This includes test compiles within the debugger as well as standalone builds.

The compiler truncates version information when building Windows applications when the version information is too long to store into the executable file. The current byte limitations for these fields are as follows:

Field Maximum length (bytes)
Long Version 79
Short Version 39
Package Info 253
Region 21
Release 11


Examples

The following code in the Action event of a PushButton causes an OutofBoundsException runtime error when the counter, i, reaches the value of FontCount.

For i=1 to FontCount
ListBox1.Addrow Font(i)
Next

Since there is no exception handler within the method, the runtime exception is passed up to the Application class, triggering the UnhandledException event.

This code in the UnhandledException event of the App class "catches" the unhandled OutOfBoundsException. Of course, it catches all unhandled OutOfBoundsExceptions throughout the application, so it doesn't know where the error occurred. You could instead place an Exception statement within the PushButton's Action event so that you can provide more specific diagnostics.

Function UnhandledException(error as RuntimeException) as Boolean
MsgBox "An OutOfBounds Exception error has occurred!"
End if
Return True


The following example toggles the GDI+ feature in Windows and refreshes the window. The code is in the Action event of a CheckBox.

App.UseGDIPlus = Me.Value
Self.Refresh

See Also

App, ResourceForkSystem, objects; AppleEvent, ConsoleApplication, MDIWindow, ServiceApplication classes.