Aztec® Programming Language
Version 1.1 Alpha 2

Copyright © 2010-2017, Aztec Development Group, All Rights Reserved

Download Aztec

Search        Contact Us

And the world's gonna sink from the weight of the human race.

- John Entwistle

 

aztec.ui.Dialog

public class Dialog from<Window>

Base

Window

Dialog

aztec.ui.IDialog

public class abstract IDialog from<Base>

Base

IDialog

The Dialog class provides a top-level dialog window which contains a single window to populate with UI controls. It does not have resize capability. The dialog can optionally be specified as "modal", meaning that no other Aztec windows for this script can be accessed until this dialog is removed. If not modal, then the user can switch back and forth between this dialog and other top-level windows within the script.

 

The Dialog can also have a menu bar and one or more toolbars. Event handlers are available for window close and window cancel events.

 

The IDialog class is an abstract interface class which contains a virtual event handler method for each of the events which the Dialog class supports.

 

The following diagram provides a complete list of valid children for the Dialog class.

Valid Child Windows for Dialog

Dialog Methods

Dialog() Constructor for theDialog class
SetIcon() Sets the icon to be displayed in the Dialog's title bar
Close() Closes the dialog and all child windows/controls
AddWindowCloseHandler() Registers an event handler for closing the dialog window using a method reference
AddWindowCloseHandler() Registers an event handler for closing the dialog window using an IDialog reference
OnWindowClose() Virtual method to handle WindowClose events by default - can be overridden

IDialog Methods

OnWindowClose() Virtual method to handle WindowClose events

Derived Classes

See Also

 


Dialog()

public method Dialog(Display TargetDisplay, int XPos, int YPos, int Width, int Height, string Title, bool IsModal = false)

Parameters

TargetDisplay

The Display object where the top-level dialog is displayed (null for local Display)

XPos

One based X position of window relative to parent

YPos

One based Y position of window relative to parent

Width

Initial width of the entire dialog window in pixels

Height

Initial height of the entire dialog window in pixels

Title

Title for the frame window

IsModal

Modal if true, not modal if false

Return Value

None

Description

Constructor for the Dialog class. The target Display is passed in (null means local Display) and the parent window is null by definition (since it is a top-level window). Base information such as position and size is also passed in.

 

If the Display object is connected to a remote UI Display Server process, the dialog window will be created on the remote machine. All child windows of the dialog will automatically be displayed on the remote machine as well. All UI events from the remote UIs are handled in the local Aztec program.

 

If the IsModal flag is true, the dialog will be treated as modal, meaning that no other top-level UI windows for this script can be accessed until this dialog is closed. If the IsModal flag is false, the user can freely switch back and forth between the top-level windows within the script. Modal dialogs prevent the user from accessing other top-level windows in the script/application (Frame, Dialog, etc.), but its use works just like any other window. When a modal Dialog is displayed, execution within the code continues just like it does for non-modal dialogs. The system does not wait for an "OK" or "Cancel" button to be pressed before execution can continue. All event handling for the modal dialog is handled just like all other windows, and the script/application is responsible for detecting that the dialog is finished (the window is closed by the user or a button is pressed that the programmer determines should take the dialog down (such as "OK" or "Cancel")). The logic in the event handlers must determine when it is appropriate to close the modal Dialog, and then perform a manual Close() (or Hide()) operation.

 

If the XPos and YPos are zero, the dialog window will be centered within the Display.

 

Note that the Dialog window is created in a "hidden" state, so the 'Show()' method must be called to display the window. This allows the script to create and initialize the entire UI before actually displaying it on the screen.

 

Dialog Class


SetIcon()

public method<bool> SetIcon(BitMap WindowIcon)

Parameters

WindowIcon

Icon image to be attached to the window

Return Value

Returns true if successful and false if not

Description

This method attaches the specified BitMap image to the Dialog window. It gets displayed in the Dialog's title bar, and also in the operating system task bar, if applicable. Note that the BitMap image must have been created as an Icon, and this method will not work if it is not a valid Icon.

 

A single Icon can have multiple images, and it is recommended that the Icon contain a 16x16 (small) icon and a 32x32 (large) icon.

 

Dialog Class


Close()

public virtual method Close()

Parameters

None

Return Value

None

Description

This virtual method closes the dialog window and all windows/controls that are children of the dialog. It can be manually called from within a WindowCloseEvent handler if the logic determines that the Close operation can continue.

 

Once a dialog window and its children are closed, the windows are no longer usable. A DisplayException will be fired if the code attempts to use one.

 

Dialog Class


AddWindowCloseHandler()

public method AddWindowCloseHandler(WindowCloseHandler Handler, Base ExtraObject = null)

Parameters

Handler

Method reference to be executed when the event occurs

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers a method reference to be executed when the dialog window is closed. The OS close icon in the dialog frame (X) will cause this event, as will pressing the button registered as a "close" button with this dialog. An optional object can also be registered which will be sent to each event handler as it is executed.

 

When the Close event occurs for the Dialog, the default UI behavior checks to see if there are one or more event handlers registered (using this or the other implementation of this same method). If there are, the handler(s) are queued up for execution. The handler(s) can decide whether or not it is safe to close the window (if document is dirty, etc.), and process accordingly. The event handler(s) must manually close the dialog window if it is appropriate based on the script/application logic. If there are no registered event handlers for the Close event, the default behavior will close the window automatically.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

The WindowCloseHandler data type represents a method reference specific to a handler for WindowCloseEvent. WindowCloseHandler is defined as follows:

 

        public type<method<WindowCloseEvent,Base>> WindowCloseHandler

 

Given this definition, the method handler must be defined with the following signature (name can be anything):

 

        public method WindowCloseMethod(WindowCloseEvent event, Base Extra) { }.

 

Dialog Class


AddWindowCloseHandler()

public method AddWindowCloseHandler(IDialog Interface, Base ExtraObject = null)

Parameters

Interface

Reference to an IDialog object

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers an IDialog interface object to be executed when the dialog window is closed. The OS close icon in the dialog frame (X) will cause this event, as will pressing the button registered as a "close" button with this dialog. An optional object can also be registered which will be sent to each event handler as it is executed. Refer to the description of the other implementation of this same method for more details.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

When the dialog window is closed, the OnWindowClose() method within the IDialog object will be executed.

 

Dialog Class


OnWindowClose()

public method virtual OnWindowClose(WindowCloseEvent CloseEvent, Base ExtraObject)

Parameters

CloseEvent

WindowCloseEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This method is the default event handler for WindowCloseEvent within the dialog. It is invoked internally as a result of the dialog window associated with this object being closed. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the Frame.AddWindowCloseHandler() method register the event handlers which get invoked by this method

 

If there are no registered event handlers, this method will close the dialog automatically...

 

If this method is overridden by a class derived from Frame, it must call this implementation of the method if it needs to execute handlers registered with the Frame.AddWindowCloseHandler() methods.

 

Frame Class


OnWindowClose()

public method virtual OnWindowClose(WindowCloseEvent CloseEvent, Base ExtraObject)

Parameters

CloseEvent

WindowCloseEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This virtual method is the event handler for WindowCloseEvent within the IDialog interface class. The method which overrides it is invoked for WindowCloseEvent within a Dialog object when the interface object is registered with the Dialog.AddWindowCloseHandler() method.

 

IDialog Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec