#include <optdialog.h>

Inheritance diagram for OptDialog:

Collaboration diagram for OptDialog:

Public Types
enum	Action { NoAction, Defaults, Reset, Accept }

Signals
void	valuesChanged (void)

void	buttonClicked (int r)

void	dialogClosed (int r)

Public Member Functions
	OptDialog (QWidget *parent=0)

	OptDialog (bool modal, QWidget *parent=0)

	OptDialog (Options &opt, const string &title, QMutex mutex=0, QWidget parent=0)

	OptDialog (Options &opt, const string &title, bool modal, QMutex mutex=0, QWidget parent=0)

	~OptDialog (void)

void	setCaption (const string &title)

OptWidget *	addOptions (Options &opt, int selectmask=0, int romask=0, int style=0, QMutex mutex=0, string tabhotkeys=0)

OptWidget *	addTabOptions (const string &label, Options &opt, int selectmask=0, int romask=0, int style=0, QMutex mutex=0, string tabhotkeys=0)

void	addWidget (QWidget *widget)

void	addTabWidget (const string &label, QWidget widget, string tabhotkeys=0)

void	addSeparator (void)

void	setVerticalSpacing (int pixel)

void	setHorizontalSpacing (int pixel)

void	setMargins (int pixel)

void	setMargins (int left, int top, int right, int bottom)

int	rejectCode (void) const

void	setRejectCode (int code)

void	clearButtons (void)

void	addButton (const string &title, OptDialog::Action action, int rcode, bool close=true, bool dflt=false)

void	addButton (const string &title, OptDialog::Action action)

void	addButton (const string &title)

int	exec (void)

Static Public Member Functions
static int	changedFlag (void)

Static Public Attributes
static const int	NoReturn = -10000

static const int	ReturnReject = -10001

Protected Slots
void	done (int r)

void	reject (void)

Detailed Description

A Dialog for editing Options.

Author: Jan Benda

Version: 1.0

Bug:: Qt bug in construct(): setResizeMode() places dialog on weired places.

This dialog widget can be used to edit the values of Options. It is based on OptWidget.

Here is an example:

This example was created with the following code:

#include <relacs/options.h>
#include <relacs/optdialog.h>
using namespace relacs;
...
Options opt1;
opt1.newSection( "Timing" );
opt1.addNumber( "duration", "Duration of Signal", 0.3527, 0.01, 1.0, 0.0001, "seconds", "ms" );
opt1.addNumber( "pause", "Pause between Signals", 0.2, 0.0, 1.0, 0.01, "seconds", "ms", "%g", 3 );
opt1.setNumber( "pause", 0.180 );
opt1.addInteger( "repeats", "Repeats", 8, 0, 100 );
opt1.newSection( "Settings" );
opt1.addText( "color", "Color", "red,green,blue");
opt1.addText( "comment", "Comments", "no comment" );
Options opt2;
opt2.addBoolean( "sinewave", "Use Sine Wave", false );
opt2.addBoolean( "loop", "Loop", true, 1 );
...
OptDialog d( this );
d.setCaption( "Example Dialog" );
d.addOptions( &opt1, 0, 1 );
d.addOptions( &opt2 );
d.setVerticalSpacing( 4 );
d.setMargins( 10 );
d.addButton( "&Ok", OptDialog::Accept, 1 );
d.addButton( "&Reset", OptDialog::Reset );
d.addButton( "&Close" );
d.exec();
...

First you have to create some Options by either defining them explicitely as in the example with the addNumber(), addText(), ... functions, or you load them from a file with the load( istream& ) function. See the documentation for Options for more details. Then you construct the OptDialog. Either the Options are passed directly to OptDialog via the constructor, or they are assigned later on with addOptions(). With addOptions() you can specify a select-mask to select a subset of the Options and a readonly-mask to specify which Options are not editable (in the example the "pause" options is not editable). Then you may define some buttons (see below) and finally you call exec() to launch the dialog.

The dialog window can be either modal or modeless. In modal mode all input to the main program from which the dialog was launched is blocked. The modality can be specified only by a constructor.

The OptDialog comes with four default buttons "Ok", "Defaults", "Reset", "Close". "Ok" copies the entered input to the corresponding Options, closes the dialog, and returns 1. "Defaults" sets the values of the input form to the corresponding default values of the Options. "Reset" sets the values of the input form to their initial values. "Close" closes the dialog without accepting the input and returns 0.

If you don't like these buttons, use the addButton() function to define your own. For example, you would get the default buttons by the following commands:

addButton( "&Ok", OptDialog::Accept, 1 );
addButton( "&Reset", OptDialog::Reset );
addButton( "&Defaults", OptDialog::Defaults );
addButton( "&Close" );

The dialog can also be closed by hitting "ESC" or by just closing the window. With setRejectCode() you can determine what value exec() returns in these cases. Default is 0.

OptDialog provides three signals: valuesChanged() is emitted whenever the Accept action is performed. buttonClicked() enables you to implement more functionality to the dialog buttons. dialogClosed() tells you that the dialog is closed. The last two signals are especially important for modeless dialogs.

The caption of the dialog can be set by setCaption(). The spacing between two input lines can be adjusted with setVerticalSpacing(). The spacing between the widget margins and its content are set with setMargins().

Member Enumeration Documentation

enum Action

Different actions for the dialog buttons.

Enumerator
NoAction	No action is associated with the button. Use this for a "Cancel" or "Close" button.
Defaults	Pressing the button sets the values of the input fields to the default values of the corresponding Options.
Reset	Pressing the button resets the values of the input fields to their initial values.
Accept	Pressing the button copies the values of the input fields to the corresponding Options. This is usually the "Ok" button.

Constructor & Destructor Documentation

OptDialog ( QWidget * parent = 0 )

Construct an empty modal dialog. This dialog will block input to the program.

Note: You still have to call exec() in order to launch the dialog.

References OptDialog::setCaption().

OptDialog	(	bool	modal,
		QWidget *	parent = `0`
	)

Construct an empty dialog with modality modal. If modal is true, this dialog will block input to the program.

Note: You still have to call exec() in order to launch the dialog.

References OptDialog::setCaption().

OptDialog	(	Options &	opt,
		const string &	title,
		QMutex *	mutex = `0`,
		QWidget *	parent = `0`
	)

Construct a modal dialog for editing the Options o. The caption of the dialog window is set to title. This dialog will block input to the program.

Note: You still have to call exec() in order to launch the dialog.

References OptDialog::addOptions(), and OptDialog::setCaption().

OptDialog	(	Options &	opt,
		const string &	title,
		bool	modal,
		QMutex *	mutex = `0`,
		QWidget *	parent = `0`
	)

Construct a dialog for editing the Options o with modality modal. The caption of the dialog window is set to title. If modal is true, this dialog will block input to the program.

Note: You still have to call exec() in order to launch the dialog.

References OptDialog::addOptions(), and OptDialog::setCaption().

~OptDialog ( void )

Destructs the OptDialog.

References OptDialog::clearButtons().

Member Function Documentation

void setCaption ( const string & title )

Set the caption of the dialog window to dialog.

Referenced by ConfigDialog::dialog(), ConfigDialog::help(), and OptDialog::OptDialog().

OptWidget * addOptions	(	Options &	opt,
		int	selectmask = `0`,
		int	romask = `0`,
		int	style = `0`,
		QMutex *	mutex = `0`,
		string *	tabhotkeys = `0`
	)

Assigns Options o to the dialog. Input forms for different Options can be placed on top of each other by multiple calls of addOptions(). Only Options with their mode() & selectmask > 0 are displayed. If selectmask ist less or equal to zero, all Options o are displayed. Options with their mode() & romask > 0 are not editable. If romask equals zero all Options o are editable. If romask() is negative none of the Options o is editable. The standard layout style = 0 puts each option into a separate line. If style = 1 then the option's identifier is in one line and the options value and unit is in the following line. tabhotkeys can point to a string that contains hotkey-characters that are already in use. This information is used to choose hotkeys for tabs. The new hotkeys are added to the string.

See Also: addTabOptions(), addWidget(), addTabWidget(), addSeparator(), addButton()

Referenced by ConfigDialog::dialogOptions(), and OptDialog::OptDialog().

OptWidget * addTabOptions	(	const string &	label,
		Options &	opt,
		int	selectmask = `0`,
		int	romask = `0`,
		int	style = `0`,
		QMutex *	mutex = `0`,
		string *	tabhotkeys = `0`
	)

Assigns Options o as a page of a TabWidget with label label to the dialog. Only Options with their mode() & selectmask > 0 are displayed. If selectmask ist less or equal to zero, all Options o are displayed. Options with their mode() & romask > 0 are not editable. If romask equals zero all Options o are editable. If romask() is negative none of the Options o is editable. The standard layout style = 0 puts each option into a separate line. If style = 1 then the option's identifier is in one line and the options value and unit is in the following line. tabhotkeys can point to a string that contains hotkey-characters that are already in use. This information is used to choose hotkeys for label and furhter tabs. The new hotkeys are added to the string.

See Also: addOptions(), addWidget(), addTabWidget(), addSeparator(), addButton()

References OptWidget::tabLabel().

void addWidget ( QWidget * widget )

Add some widget to the dialog. The widget is deleted when the dialog is closed.

See Also: addOptions(), addTabOptions(), addTabWidget(), addButton()

Referenced by ConfigDialog::dialogEmptyMessage(), ConfigDialog::dialogHeaderWidget(), and ConfigDialog::help().

void addTabWidget	(	const string &	label,
		QWidget *	widget,
		string *	tabhotkeys = `0`
	)

Add some widget as a page of a TabWidget with label label to the dialog. The widget is deleted when the dialog is closed. tabhotkeys can point to a string that contains hotkey-characters that are already in use. This information is used to choose a hotkey for label. The new hotkey is added to the string.

See Also: addOptions(), addTabOptions(), addWidget(), addSeparator(), addButton()

References OptWidget::tabLabel().

void addSeparator ( void )

Add a separator line to the dialog.

See Also: addOptions(), addTabOptions(), addWidget(), addTabWidget(), addButton()

void setVerticalSpacing ( int pixel )

Set the spacing between the lines to pixel pixel. Call this function after you added all Options to the dialog with addOptions().

See Also: setHorizontalSpacing(), setMargins()

Referenced by ConfigDialog::dialogOptions().

void setHorizontalSpacing ( int pixel )

Set the horizontal spacing to pixel pixel. Call this function after you added all Options to the dialog with addOptions().

See Also: setVerticalSpacing(), setMargins()

void setMargins ( int pixel )

Set the spacing between the widget margins and its content to pixel pixel. Call this function after you added all Options to the dialog with addOptions().

See Also: setVerticalSpacing(), setHorizontalSpacing()

Referenced by OptDialog::setMargins().

void setMargins	(	int	left,
		int	top,
		int	right,
		int	bottom
	)

Set the spacing between the widget margins and its content to all sides individually. Call this function after you added all Options to the dialog with addOptions().

See Also: setVerticalSpacing(), setHorizontalSpacing()

References OptDialog::setMargins().

int rejectCode ( void ) const

The code exec() returns if the dialog is closed by entering "ESC" or by closing the window. The default reject code is 0. The reject code can be set to a different value by setRejectCode(). rejectCode() returns the actual set reject code.

See Also: addButton()

void setRejectCode ( int code )

Set the code exec() returns if the dialog is closed by entering "ESC" or by closing the window to code.

See Also: addButton(), rejectCode()

Referenced by ConfigDialog::dialogButtons().

void clearButtons ( void )

Remove all buttons. You normally don't have to call this functions, since the default buttons are removed automatically by the first call of addButton().

See Also: addButton(), setRejectCode()

Referenced by OptDialog::addButton(), and OptDialog::~OptDialog().

void addButton	(	const string &	title,
		OptDialog::Action	action,
		int	rcode,
		bool	close = `true`,
		bool	dflt = `false`
	)

Add a button with label title to the OptDialog. Clicking the button will execute the action specified by the Action action (NoAction, Defaults, Reset, Accept). The dialog is closed if close is true and exec() is returning rcode. If default is true than this button will be activated when hitting "Return". If no default button is specified, the first button with the Accept action and a return value will be the default button.

See Also: clearButtons(), setRejectCode()

References OptDialog::buttonClicked(), OptDialog::clearButtons(), OptDialog::done(), and OptDialog::valuesChanged().

Referenced by OptDialog::addButton(), ConfigDialog::dialogButtons(), ConfigDialog::dialogEmptyMessage(), and ConfigDialog::help().

void addButton	(	const string &	title,
		OptDialog::Action	action
	)

inline

Add a button with label title to the OptDialog. Clicking the button will execute the action specified by the Action action (NoAction, Defaults, Reset, Accept). The dialog is not closed and the buttom does not emit a buttonClicked() signal.

See Also: clearButtons()

References OptDialog::addButton(), and OptDialog::NoReturn.

void addButton ( const string & title )

inline

Add a button with label title to the OptDialog. Clicking the button will close the dialog without accepting the input. The dialog returns rejectCode() (default 0). This function is for creating a "Close" or "Cancel" button.

See Also: clearButtons(), setRejectCode()

References OptDialog::addButton(), OptDialog::NoAction, and OptDialog::ReturnReject.

int exec ( void )

Opens the dialog window. If the OptDialog is modal, exec() blocks until the dialog is finished and returns the return code of the button that was clicked, or rejectCode() if the window was closed. If the dialog is modeless, exec() returns immediately and returns rejectCode(). The default reject code is 0. Use the dialogClose() - signal to process the return value of a modeless dialog.

See Also: addOptions(), addButton(), setRejectCode()

Referenced by ConfigDialog::dialog(), and ConfigDialog::help().

static int changedFlag ( void )

inlinestatic

The flag that is used to mark options whose value were changed by or-ing their mode with this flag. It is preset to a constant value (32768) and cannot be changed by the user.

References OptWidget::changedFlag().

Referenced by OptDialogButton::clicked().

void valuesChanged ( void )

signal

This signal is emitted when a button with the Accept Action is clicked, i.e. right after the values of the input fields have been copied to the corresponding Options. The notify() function of all Options are called after the values of the input fields are copied to the Options and before this signal is emitted, i.e. one can in each Options' notify() function assume that other Options have already the new values.

Referenced by OptDialog::addButton().

void buttonClicked ( int r )

signal

This signal is emitted when a button with a return value is clicked. r is the return value of the button. The signal is usefull for modeless dialogs.

Referenced by OptDialog::addButton().

void dialogClosed ( int r )

signal

This signal is emitted when the dialog is closed. r is the return value of the dialog, which equals for modal dialogs the return value of exec(). The signal is usefull for modeless dialogs.

Referenced by OptDialog::done().

void done ( int r )

protectedslot

Reimplemented for internal reasons.

References OptDialog::dialogClosed().

Referenced by OptDialog::addButton(), and OptDialog::reject().

void reject ( void )

protectedslot

Reimplemented for internal reasons.

References OptDialog::done().

Member Data Documentation

const int NoReturn = -10000

static

Use this for the return value of a button if this button should not emit a buttonClicked() or dialogClosed() signal. Like for example a "Reset" or "Clear" button.

Referenced by OptDialog::addButton(), and OptDialogButton::clicked().

const int ReturnReject = -10001

static

The return value for a button whose return code should equal the rejectCode(). Like for example a "Close" or "Cancel" button.

Referenced by OptDialog::addButton(), and OptDialogButton::create().

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

Public Types

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Slots

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation