MGUI::DLGSHELL Class Reference

Base class for general dialog support for both modeless and modal behavior. More...

#include <mgui/dlgshell.h>

Inheritance diagram for MGUI::DLGSHELL:

[legend]

Public Types
enum	BUTTONS { BUTTONS_Default = 0x00, BUTTON_OK = 0x01, BUTTON_Cancel = 0x02, BUTTON_Apply = 0x04, BUTTON_Close = 0x08, BUTTON_Help = 0x10 }
enum	STYLE { STYLE_Default = 0x0000, STYLE_Resizable = 0x0001, STYLE_ContextHelp = 0x0002, STYLE_AllowMinimize = 0x0004, STYLE_AllowMaximize = 0x0008, STYLE_CenterOnScreen = 0x0010, STYLE_CenterOnMouse = 0x0020, STYLE_DeleteOnClose = 0x0040, STYLE_ToolWindow = 0x0080, STYLE_AllowMenuBar = 0x0100, STYLE_NoDestroyModal = 0x0200, STYLE_KeepOnTop = 0x0400 }
Public Member Functions
virtual	~DLGSHELL ()=0
void	Close (bool notify=true)
ERRVALUE	CreateModeless (MDLGPARENT dlgparent, bool AllowMinimize=false)
ERRVALUE	DoModal (MDLGPARENT dlgparent)
bool	GetKeepOnTop () const
bool	IsOpen () const
ERRVALUE	Open ()
	operator MDLGPARENT () const
void	SetApplyEnabled (bool enabled=true)
void	SetDeleteOnClose (bool DeleteOnClose=true)
void	SetKeepOnTop (bool KeepOnTop=true)
void	SetOkEnabled (bool enabled=true)
Protected Member Functions
	DLGSHELL (const MISTRING &title, HELPID HelpID, STYLE style=STYLE_Default)
MGUI::CTRL_PUSHBUTTON &	CreateButton (BUTTONS button, const MISTRING &label)
MGUI::CTRL_PUSHBUTTON &	CreateButton (BUTTONS button)
void	CreateButtons (BUTTONS buttons=BUTTONS_Default)
MGUI::LAYOUT_PANE &	GetButtonPane (bool AddSpace=true)
bool	IsModal () const
void	NotifyCancel ()
void	NotifyOK ()
ERRVALUE	OpenModal (MDLGPARENT dlgparent)
void	SetIgnoreNonVisible (bool IgnoreNonVisible=true)
void	SetReturnValue (int RetValue)
void	SetRootMargin (int RootMargin)
void	SetRootSpacing (int RootSpacing)
void	SetStyle (STYLE style)
DEPRECATED void	UpdateLayout ()
virtual void	v_OnCancel ()
virtual void	v_OnOK ()
ERRVALUE	WaitForClose ()
Private Member Functions
virtual ERRVALUE	v_CreateContent ()=0
virtual void	v_OnApply ()
virtual void	v_OnClose ()
virtual void	v_OnCloseRequest ()
virtual void	v_OnDestroy ()
virtual void	v_OnOpen ()

Detailed Description

Base class for general dialog support for both modeless and modal behavior.

The derived dialog implementation class must override the v_CreateContent() method. Most derived classes will also override v_OnApply to perform the desired update of the external data when the user presses 'OK' or 'Apply'. When overriding the protected v_On...() virtual methods pay close attention to when the corresponding base method is to be called to ensure correct behavior.

Member Enumeration Documentation

enum MGUI::DLGSHELL::BUTTONS

Standard dialog button selections, may be combined for some methods.

Enumerator:

BUTTONS_Default	Default buttons per dialog style.
BUTTON_OK
BUTTON_Cancel
BUTTON_Apply
BUTTON_Close
BUTTON_Help

enum MGUI::DLGSHELL::STYLE

Style settings, may be combined.

Enumerator:

STYLE_Default	Default style.
STYLE_Resizable	Dialog is resizable.
STYLE_ContextHelp	(Non-X) Include '?' icon in titlebar, cannot combine with AllowMinimize or AllowMaximize
STYLE_AllowMinimize	(Non-X) Include minimize box in titlebar, cannot combine with STYLE_ContextHelp
STYLE_AllowMaximize	(Non-X) Include maximize box in titlebar, cannot combine with STYLE_ContextHelp
STYLE_CenterOnScreen	Initially center dialog on monitor containing parent window.
STYLE_CenterOnMouse	Initially center dialog on mouse cursor.
STYLE_DeleteOnClose	Delete (destroy) dialog on closing, only used for modeless dialogs.
STYLE_ToolWindow	Window is a "tool controls" or "pallette" window. Gets a smaller title bar than normal windows.
STYLE_AllowMenuBar	Dialog can contain a menubar.
STYLE_NoDestroyModal	Don't destroy the modal dialog on close.
STYLE_KeepOnTop	Keep dialog above other windows.

Reimplemented in MGUI::DLG_TEXTVIEW, MGUI::DLG_HTML, and RVC::DLG_IMAGE_HISTOGRAM.

Constructor & Destructor Documentation

virtual MGUI::DLGSHELL::~DLGSHELL ( ) [pure virtual]

Destructor.

MGUI::DLGSHELL::DLGSHELL	(	const MISTRING &	title,
		HELPID	HelpID,
		STYLE	style = `STYLE_Default`
	)			`[protected]`

Constructor, initializes only.

Parameters:

	title	Title string, can use TEXTID also
	HelpID	Help ID, use HELPID__None if no 'help' available
	style	Dialog style settings

Member Function Documentation

void MGUI::DLGSHELL::Close ( bool notify = true )

Close the dialog if modeless.

Parameters:

notify

Notify via OnClose()

MGUI::CTRL_PUSHBUTTON& MGUI::DLGSHELL::CreateButton	(	BUTTONS	button,
		const MISTRING &	label
	)			`[protected]`

Create single button with MISTRING label.

Returns:: Reference to button created (usually for alignment only).

Parameters:

button

Button to create

MGUI::CTRL_PUSHBUTTON& MGUI::DLGSHELL::CreateButton ( BUTTONS button ) [protected]

Create single button with standard label.

Returns:: Reference to button created (usually for alignment only).

Parameters:

button

Button to create

void MGUI::DLGSHELL::CreateButtons ( BUTTONS buttons = BUTTONS_Default ) [protected]

Create standard buttons at bottom of dialog.

Default button labels will depend on the dialog style. Modal dialog buttons will be 'OK', 'Cancel' and 'Help'. Modeless dialog buttons will be 'OK', 'Cancel', 'Apply' and 'Help'. For modeless dialogs, pressing 'OK' has the same effect as pressing 'Apply' followed by 'Close'.

Parameters:

buttons

Buttons to create

ERRVALUE MGUI::DLGSHELL::CreateModeless	(	MDLGPARENT	dlgparent,
		bool	AllowMinimize = `false`
	)

Create 'modeless' dialog (without opening it).

Parameters:

	dlgparent	Parent for dialog
	AllowMinimize	(Non-X) Allow dialog to be "minimized"

ERRVALUE MGUI::DLGSHELL::DoModal ( MDLGPARENT dlgparent )

Open dialog in modal state and wait for user to dismiss via OK/Cancel.

Returns:: 0 if OK, EUserCancel if Cancel, < 0 if error

Parameters:

dlgparent

Parent for modal dialog

MGUI::LAYOUT_PANE& MGUI::DLGSHELL::GetButtonPane ( bool AddSpace = true ) [protected]

Get pane to create buttons at bottom of dialog.

This allows additional 'non-standard' buttons to be added to the dialog. This will create the pane if it has not been created already.

Parameters:

AddSpace

Add space if creating so buttons placed at right

bool MGUI::DLGSHELL::GetKeepOnTop ( ) const

Get the KeepOnTop state of the window.

bool MGUI::DLGSHELL::IsModal ( ) const [inline, protected]

Determine if dialog was open as modal.

bool MGUI::DLGSHELL::IsOpen ( ) const

Determine if dialog is currently open.

void MGUI::DLGSHELL::NotifyCancel ( ) [inline, protected]

Send 'Cancel' notification to dialog.

void MGUI::DLGSHELL::NotifyOK ( ) [inline, protected]

Send 'OK' notification to dialog.

ERRVALUE MGUI::DLGSHELL::Open ( )

Open dialog if created in modeless state.

ERRVALUE MGUI::DLGSHELL::OpenModal ( MDLGPARENT dlgparent ) [protected]

Open dialog in "modal" state, and return immediately.

This is intended for use only in very limited cases (such as status dialog).

MGUI::DLGSHELL::operator MDLGPARENT ( ) const [inline]

Cast to MDLGPARENT for use as parent for other dialogs.

void MGUI::DLGSHELL::SetApplyEnabled ( bool enabled = true ) [inline]

Set whether 'Apply' (if exists) button is enabled.

void MGUI::DLGSHELL::SetDeleteOnClose ( bool DeleteOnClose = true )

Set to delete shell instance when closed (for modal dialogs).

This allows the dialog to be created via 'new' without retaining the pointer instance.

void MGUI::DLGSHELL::SetIgnoreNonVisible ( bool IgnoreNonVisible = true ) [inline, protected]

Set to ignore nonvisible items when doing layout.

This must be called before CreateModeless() or DoModal() and is usually done in the subclass constructor.

void MGUI::DLGSHELL::SetKeepOnTop ( bool KeepOnTop = true )

Set (or clear) the KeepOnTop state of the window.

void MGUI::DLGSHELL::SetOkEnabled ( bool enabled = true ) [inline]

Set whether 'OK' button (if exists) is enabled.

void MGUI::DLGSHELL::SetReturnValue ( int RetValue ) [inline, protected]

Set value to return from dialog.

void MGUI::DLGSHELL::SetRootMargin ( int RootMargin ) [inline, protected]

Set margin for root pane.

This must be called before CreateModeless() or DoModal() and is usually done in the subclass constructor.

void MGUI::DLGSHELL::SetRootSpacing ( int RootSpacing ) [inline, protected]

Set spacing for root pane.

This must be called before CreateModeless() or DoModal() and is usually done in the subclass constructor.

void MGUI::DLGSHELL::SetStyle ( STYLE style ) [inline, protected]

Set dialog style.

This must be called before CreateModeless() or DoModal() and not in v_OnInitDialog() for proper behavior.

DEPRECATED void MGUI::DLGSHELL::UpdateLayout ( ) [inline, protected]

Force update of dialog layout.

virtual ERRVALUE MGUI::DLGSHELL::v_CreateContent ( ) [private, pure virtual]

Create dialog shell contents.

Derived class MUST implement this. Function must return 0 for success or an error code. This will be called by the dialog creation code and must not be called directly. This is normally overridden only by the specific dialog implementation and not by the code that actually uses that dialog implementation. Implementation should call GetMainForm() or GetMainPane() to determine the form or pane to create the controls in. Note that you cannot override the dialog title in v_CreateContent, title must be set first. This function should not open another dialog, modal or non-modal.

Implements MGUI::SHELL.

Implemented in MGUI::DLG_SPATMOD_IMAGE_VIEW, MGUI::DLG_XML, GPSDATABASE::DLG_IMPORTTXT, and RVC::UI::DLG_EDIT_RASTER_VALUE.

virtual void MGUI::DLGSHELL::v_OnApply ( ) [private, virtual]

Called when user presses 'Apply' button.

Will also be called by default v_OnOK implementation if 'Apply' button exists and is not disabled.

Reimplemented in MGUI::DLG_XML.

virtual void MGUI::DLGSHELL::v_OnCancel ( ) [protected, virtual]

Called when 'Cancel' button is pressed.

Derived class must call base class v_OnCancel() method AFTER performing its own processing to actually close the dialog. In some cases the user may be given an opportunity to verify that they intended to press the Cancel button. If they elect not to cancel then the base class v_OnCancel() method should not be called. This will cause the dialog to remain open and allow the user to retain the settings. Derived classes should generally declare this method as private.

Reimplemented in MGUI::DLG_XML, and GPSDATABASE::DLG_IMPORTTXT.

virtual void MGUI::DLGSHELL::v_OnClose ( ) [private, virtual]

Called when dialog gets closed.

Reimplemented in MGUI::DLG_SPATMOD_IMAGE_VIEW, MGUI::DLG_XML, and RVC::UI::DLG_DB_FIELD_REVALUE.

virtual void MGUI::DLGSHELL::v_OnCloseRequest ( ) [private, virtual]

Called when user requests that shell be 'closed'.

Default implementation simply calls Close(). May be overridden if different behavior desired.

Implements MGUI::SHELL.

Reimplemented in MGUI::DLG_XML.

virtual void MGUI::DLGSHELL::v_OnDestroy ( ) [private, virtual]

Called when dialog is destroyed.

Reimplemented in MGUI::DLG_XML.

virtual void MGUI::DLGSHELL::v_OnOK ( ) [protected, virtual]

Called when 'OK' button is pressed.

Derived class must call base class v_OnOK() method AFTER performing its own processing to actually close the dialog. If the dialog settings do not pass their associated validation test then an appropriate message should be displayed for the user and the base class v_OnOK() method should not be called. This will cause the dialog to remain open and allow the user to correct the settings. In addition, if an 'Apply' button has been created using the appropriate DLGSHELL methods then v_OnApply will be called before closing. Derived classes should generally declare this method as private.

Reimplemented in MGUI::DLG_XML, and GPSDATABASE::DLG_IMPORTTXT.

virtual void MGUI::DLGSHELL::v_OnOpen ( ) [private, virtual]

Called after dialog is actually opened.

Reimplemented in MGUI::DLG_SPATMOD_IMAGE_VIEW, and MGUI::DLG_XML.

ERRVALUE MGUI::DLGSHELL::WaitForClose ( ) [protected]

Wait for user to close dialog.

Should only be used for modal dialogs.

The documentation for this class was generated from the following file:

mgui/dlgshell.h

MGUI::DLGSHELL Class Reference

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation