VCF::Dialog Class Reference
A Dialog is a popup frame that is generally used for user input. More...
#include <vcf/ApplicationKit/Dialog.h>
Inheritance diagram for VCF::Dialog:
Public Types | |
| enum | MessageStyle { msDefault = 0, msError, msInfo, msWarning, msQuestion } |
| enum | MessageButtons { mbOK = 1, mbHelp = 2, mbYesNo = 4, mbYesNoCancel = 8, mbOKCancel = 16, mbRetryCancel = 32, mbAbortRetryIgnore = 64 } |
| enum | DialogEvents { deSheetModalFinished = CONTROL_EVENTS_LAST + 1241, deModalFinished } |
| enum | ModalState { msNonModal = 0, msAppModal = 1, msSheetModal = 2 } |
Public Member Functions | |
| Dialog (Control *owner=NULL) | |
| virtual void | setCaption (const String &caption) |
| Sets the caption for the frame. | |
| virtual void | paint (GraphicsContext *context) |
| Paints the control. | |
| virtual Rect | getClientBounds (const bool &includeBorder=true) |
| overridden to take into account client bounds | |
| virtual void | setClientBounds (Rect *bounds) |
| Sets the client bounds only. | |
| virtual UIToolkit::ModalReturnType | showModal () |
| This displays the dialog and enters into an application modal state. | |
| virtual void | showSheetModal () |
| This function returns once the dialog is displayed, but is considered "modal" for the window that owns it. | |
| virtual void | show () |
| Shows the frame. | |
| virtual void | close () |
| Closes the Frame. | |
| UIToolkit::ModalReturnType | getModalReturnValue () |
| void | setModalReturnValue (const UIToolkit::ModalReturnType &returnType) |
| virtual void | setFrameStyle (const FrameStyleType &frameStyle) |
| Sets the frame style @ see FrameStyleType. | |
| virtual bool | allowsActivation () |
| Indicates to the framework whether or not this frame should allow activation. | |
| virtual void | setIconImage (Image *icon) |
| Sets the icon image. | |
| virtual Image * | getIconImage () |
| Returns the current image for the frames icon. | |
| virtual bool | isActiveFrame () |
| Control * | getOwner () |
Returns the owner of the component. | |
| bool | isModal () |
| returns true if the dialog's Dialog::showModal() method was called to display teh dialog (indicating that a modal event loops is active), other wise it returns false, indicating non-modal behaviour. | |
| bool | isSheetModal () |
| virtual void | keyDown (KeyboardEvent *e) |
| called when the user presses the key down | |
Static Public Member Functions | |
| static void | showMessage (const String &message, const String &caption="") |
| static UIToolkit::ModalReturnType | showMessage (const String &message, const String &caption, const int32 &messageButtons=mbOKCancel, const MessageStyle &messageStyle=msDefault) |
Public Attributes | |
| VCF::Delegate | SheetModalFinished |
| VCF::Delegate | ModalFinished |
Protected Member Functions | |
| void | onDialogClose (Event *event) |
| void | onPostClose (Event *e) |
| void | showWithModalState (ModalState state) |
| virtual | ~Dialog () |
Protected Attributes | |
| DialogPeer * | dialogPeer_ |
| WindowPeer * | windowPeer_ |
| Control * | owner_ |
| Control * | previousFocusedControl_ |
| UIToolkit::ModalReturnType | returnValue_ |
| ModalState | modal_ |
Detailed Description
A Dialog is a popup frame that is generally used for user input.A Dialog has a special state variable that tells what the "mode" of the dialog is. This mode is determined not by how the dialog is created but rather by how the dialog is displayed which is done by calling either Dialog:show(), Dialog::showModal(), or Dialog::showSheetModal(). Each of these sets the dialog's modal state to either modeless, modal, or sheet modal. A modeless dialog is visible till the user closes the dialog, but it doesn't prevent the use from changing focus back to the orginal window that launched the dialog. A modal, or application modal, dialog, disables everything else, and enters into a modal event loop that does not end till the dialog is closed. Nothing else can be accomplished in the UI till the dialog is closed. A sheet modal dialog is used to attach a dialog to a specific window, and while the dialog is visible the window that launched (also known as the owner window) the dialog is disabled, but all other UI activity can still take place. When the sheet modal dialog is closed the owner window is enabled again for UI input.
Think of a sheet modal dialog as a middle ground between modeless and application modal.
A dialog's UI is normally a frame with a close button, and optionally a help and system button as well. The caption is the standard height.
- Event Delegates for this class:
Member Enumeration Documentation
|
|
|
|
|
|
|
|
|
|
|
|
Constructor & Destructor Documentation
|
|
|
|
|
|
Member Function Documentation
|
|
Indicates to the framework whether or not this frame should allow activation. Som frames do not support becoming activated, for example the tooltip frame, or the frame that houses the dropdown list for the ComboBoxControl. Must be implemented by derived classes. Implements VCF::Frame. |
|
|
Closes the Frame. Must be implemented by classes that derive from Frame. Implements VCF::Frame. |
|
|
overridden to take into account client bounds
Reimplemented from VCF::Control. |
|
|
Returns the current image for the frames icon.
Implements VCF::Frame. |
|
|
|
|
|
The owner (you could also think of this as the component's "parent") is responsible for destroying the component when the owner is destroyed.
Reimplemented from VCF::Component. |
|
|
Implements VCF::Frame. |
|
|
returns true if the dialog's Dialog::showModal() method was called to display teh dialog (indicating that a modal event loops is active), other wise it returns false, indicating non-modal behaviour.
|
|
|
|
|
|
called when the user presses the key down
Reimplemented from VCF::Control. |
|
|
|
|
|
|
|
|
Paints the control. Called by the underlying windowing system whenever the control needs to be painted. Note that in some cases the GraphicsContext passed in to this method may not be the same pointer as the GraphicsContext that the control holds itself. During the paint() method you should only use the context value for all your drawing and not the one returned in getContext(). The value returned by getContext() should be used for drawing that takes place outside of the paint() method. If the control allows paint notification, then the framework will fire an event to the BeforeControlPainted delegate prior to calling the control's paint() method. After the paint() method has returned, if the control allows paint notification, the framework will fire an event to the AfterControlPainted delegate. This allows outside observers to take part in the paint cycle, but beware that this does come at a bit of a cost, so use this feature sparingly. Note: This should NEVER be called by programmers using the VCF, it will be called for you during the course of your applications native event loop, and is only here for providing custom drawing routines for controls. In other words: you implement it, you never call it yourself.
Reimplemented from VCF::Frame. |
|
|
Sets the caption for the frame. While the exact effects of calling this method depend on windowing system the VCF is running on, in general a caption is displayed on the top of the frame, and is generally a non client area. This method will change the text that is displayed there.
Reimplemented from VCF::Frame. |
|
|
Sets the client bounds only.
Implements VCF::Frame. |
|
|
Sets the frame style @ see FrameStyleType.
Implements VCF::Frame. |
|
|
Sets the icon image. The behaviour of this is partially windowing system dependent, and some systems (Mac OSX, for example, or some X11 window managers) may choose to ignore this. However, typically the icon is displayed in the top left corner of the frame, in the non client area that houses the caption. Implements VCF::Frame. |
|
|
|
|
|
Shows the frame. Generally the same as calling Control::setVisible(true) It also activates it.
Reimplemented from VCF::Frame. Reimplemented in VCF::MessageDialog. |
|
||||||||||||||||||||
|
|
|
||||||||||||
|
|
|
|
This displays the dialog and enters into an application modal state. This function will not return till the modal event loop is finished. The event loop can be finished by the user clicking on the close button of the dialog (if present), or by clicking on one of the button present on the dialog's UI. Alternately the user may hit the "Esc" key and this will also close the dialog and quit the modal event loop. The same can be achieved programmatically by calling the dialog's close() method. Reimplemented in VCF::MessageDialog. |
|
|
This function returns once the dialog is displayed, but is considered "modal" for the window that owns it. If this is called and no owner window has been specified for the dialog, then an exception is thrown. The idea is to have a dialog that is part or related to the functionality of a specific window (probabably a document window). Unlike showModal() which puts the entire application into a modal state and does not return till the modal event loop is finished, showSheetModal() returns. To get the "modal" result, you should add a custom event handler to the SheetModalFinished delegate. When the dialog is closed the SheetModalFinished delegate will fire an event that contains the modal result value.
|
|
|
|
Member Data Documentation
|
|
|
|
|
|
|
|
|
|
|
Reimplemented from VCF::Component. |
|
|
|
|
|
|
|
|
|
|
|
|
The documentation for this class was generated from the following file:
- vcf/ApplicationKit/Dialog.h