gui::Menu Class Reference

Menu and Toolbar management. More...

#include <menu.h>

Public Member Functions
	Menu (QMainWindow *_main)
	~Menu ()
QString	getAction (int index)
QMenuBar *	loadMenu (QWidget *parent) throw (InvalidMenuException)
ToolBarList	loadToolBars () throw (InvalidMenuException)
ToolBar *	getToolbar (const QString &name)
QStringList	getToolbarList ()
void	saveToolbars ()
void	restoreToolbars ()
const QPixmap *	getIcon (const QString &name)
const QIconSet *	getIconSet (const QString &name)
void	loadItem (const QString &name, QMenuData *parent=NULL, QStringList prev=QStringList()) throw (InvalidMenuException)
void	enableByName (const QString &name, bool enable)
void	checkByName (const QString &name, bool check)
void	showByName (const QString &name, bool show)
void	createItem (const QString &parentName, const QString &name, const QString &caption, const QString &action, const QString &accel=QString::null, const QString &icon=QString::null, const QStringList &classes=QStringList()) throw (InvalidMenuException)
void	setTextByName (const QString &name, const QString &newText)
QString	getTextByName (const QString &name)
Static Public Member Functions
static QString	pop (QStringList::ConstIterator &it, const QStringList::ConstIterator &end)
static char	getAccel (const QString &name)
static QString	readItem (const QString &name) throw (InvalidMenuException)
static bool	isList (const QString &line)
static QString	parseName (QString &line, const QString &name=QString::null) throw (InvalidMenuException)
static bool	chopCommand (QString &line, const QString &command)
static void	invalidItem (const QString &type, const QString &name, const QString &line, const QString &expected=QString::null) throw (InvalidMenuException)
Private Member Functions
QString	menuItemText (const QString &caption, const QString &name)
QString	toolTipText (const QString &text, const QString &name, QString accel=QString::null)
ToolButton *	createToolBarItem (ToolBar *tb, const QString &name, const QString &text, const QString &action, const QString &accel, const QString &icon, const QStringList &classes=QStringList())
void	addToMap (const QString &name, QWidget *item)
void	addToMap (const QString &name, QMenuData *parent, int itemId)
void	addItem (QString line, QMenuData *parent, const QString &name=QString::null) throw (InvalidMenuException)
int	addItem (QMenuData *parent, const QString &name, const QString &caption, const QString &action, const QString &accel=QString::null, const QString &icon=QString::null, const QStringList &classes=QStringList()) throw (InvalidMenuException)
bool	reserveAccel (const QString &accelDef, const QString &action)
int	addAction (const QString &action)
void	loadItemsDef (QString line, QMenuData *menu, QStringList prev=QStringList()) throw (InvalidMenuException)
void	loadItems (const QString &name, QMenuData *menu, QStringList prev=QStringList()) throw (InvalidMenuException)
void	loadToolBarItem (ToolBar *tb, const QString &item) throw (InvalidMenuException)
ToolBar *	loadToolbar (const QString &name, bool visible=true) throw (InvalidMenuException)
void	optimizeItems (QMenuData *menu)
Private Attributes
ActionMap	action_map
ActionMapInverse	action_map_i
int	action_index
QStringList	toolbarNames
ToolBarList	toolbarList
AccelList	accels
QMap< QString, QString >	itemText
QMap< QString, QString >	accelText
MenuCache	mCache
MenuNames	mCacheName
MenuAccels	mAccel
IconCache *	cache
QMainWindow *	main
MenuItems	mapMenu
ToolbarItems	mapTool
int	seqId
QMenuBar *	menubar

Detailed Description

Menu and Toolbar management.

This class manages Menu, Toolbars and Shortcuts.
Menus, menu items, toolbars and toolbar items share the same namespace and often menu and toolbar items are interchangable (only difference is that toolbar item must have icon, while menu item can be without an icon)
For more information about menus and toolbars, check doc/design/gui/menu.xml

Constructor & Destructor Documentation

gui::Menu::Menu ( QMainWindow * _main )

Contructor of menu system for one specific window

Parameters:

_main

Main application window

gui::Menu::~Menu ( )

Destructor

Member Function Documentation

int gui::Menu::addAction ( const QString & action ) [private]

Adds action to menu, returning newly allocated menu Id or existing menu id if action is already present

Parameters:

action

Name of action

Returns:: Menu ID of the specified action

int gui::Menu::addItem	(	QMenuData *	parent,
		const QString &	name,
		const QString &	caption,
		const QString &	action,
		const QString &	accel = `QString::null`,
		const QString &	icon = `QString::null`,
		const QStringList &	classes = `QStringList()`
	)			throw (InvalidMenuException) `[private]`

Add menu item specified by given data to parent

Parameters:

	parent	parent menu in which this item will be appended
	name	Name of the item. Key in settings, or specified from script. Have to be unique
	caption	Caption of item (untranslated)
	action	Script to execute when the item is selected
	accel	Keyboard Accelerator
	icon	Name of icon
	classes	Item classes

Returns:: ID of item just added

void gui::Menu::addItem	(	QString	line,
		QMenuData *	parent,
		const QString &	name = `QString::null`
	)			throw (InvalidMenuException) `[private]`

Add menu item specified by given data to parent

Parameters:

	line	Line containing menu item specification
	parent	parent menu in which this item will be appended
	name	Name of this item (key in settings).

void gui::Menu::addToMap	(	const QString &	name,
		QMenuData *	parent,
		int	itemId
	)			`[private]`

Add specified menu item to "all items" map

Parameters:

	name	Name of item
	parent	Parent menu
	itemId	Id of item in parent menu

void gui::Menu::addToMap	(	const QString &	name,
		QWidget *	item
	)			`[private]`

Add specified toolbar item to "all items" map

Parameters:

	name	Name of item
	item	The toolbutton or widget

Referenced by getIcon().

void gui::Menu::checkByName	(	const QString &	name,
		bool	check
	)

Check or uncheck item in toolbar and/or menu, given its name
Note: Toolbuttons will automatically convert to Togglable toolbuttons this way and will start togling itself automatically on each succesive click

Parameters:

	name	Name of item
	check	True to check, false to uncheck

bool gui::Menu::chopCommand	(	QString &	line,
		const QString &	command
	)			`[static]`

Try to remove command string from line. Return true, if command was found and removed from line, false if command was not found (and line is unchanged)

Parameters:

	line	input line
	command	Command to look for

Returns:: presence of command in line

void gui::Menu::createItem	(	const QString &	parentName,
		const QString &	name,
		const QString &	caption,
		const QString &	action,
		const QString &	accel = `QString::null`,
		const QString &	icon = `QString::null`,
		const QStringList &	classes = `QStringList()`
	)			throw (InvalidMenuException)

Load one menu or toolbar item and insert it into parent menu or toolbar. If inserting into toolbar and name refers to special toobar item, that item is inserted and rest of parameters are ignored

Parameters:

	parentName	Name of parent menu/toolbar. If NULL/empty, main menubar is the parent
	name	Name of the item. Have to be unique. ("" or "-" will insert separator and ignore rest of parameters)
	caption	Caption of item
	action	Script to execute when the item is selected
	accel	Keyboard Accelerator
	icon	Name of icon
	classes	Item classes

ToolButton * gui::Menu::createToolBarItem	(	ToolBar *	tb,
		const QString &	name,
		const QString &	text,
		const QString &	action,
		const QString &	accel,
		const QString &	icon,
		const QStringList &	classes = `QStringList()`
	)			`[private]`

Create single toolbar button and add it to toolbar

Parameters:

	tb	Toolbar for addition of item
	name	Name of the item. Key in settings, or specified from script. Have to be unique
	text	Tooltip of item (untranslated)
	action	Script to execute when the item is selected
	accel	Keyboard Accelerator
	icon	Name of icon
	classes	Item classes

Returns:: pointer to toolbutton just added

void gui::Menu::enableByName	(	const QString &	name,
		bool	enable
	)

Enable or disable item in toolbar and/or menu, given its name

Parameters:

	name	Name of item
	enable	True to enable, false to disable

char gui::Menu::getAccel ( const QString & name ) [static]

Get accelerator for given description

Parameters:

name

Name of menu item

Returns:: accelerator (the character after '&')

QString gui::Menu::getAction ( int index )

Return action string from given menu ID

Parameters:

index

Menu ID of action

Returns:: Name of the specified action

Referenced by gui::QSMenu::getAction().

const QPixmap * gui::Menu::getIcon ( const QString & name )

Returns icon with given name from cache (loading if necessary)

Parameters:

name

Name of icon to get

Returns:: Pixmap containing specified icon

References addToMap().

const QIconSet * gui::Menu::getIconSet ( const QString & name )

Returns icon set with given name from cache (creating if necessary)

Parameters:

name

Name of icon set to get

Returns:: specified Icon set

Referenced by gui::QSMenu::addItemDef().

QString gui::Menu::getTextByName ( const QString & name )

Given name of toolbar or menu item, return its text This will return original (untranslated) text (in english) Setting it back with setTextByName will translate it according to the translation file

Parameters:

name

Name of the item

Returns:: text on the item

ToolBar * gui::Menu::getToolbar ( const QString & name )

Return toolbar with given name.

Parameters:

name

Name of toolbar

Returns:: Toolbar, or NULL if toolbar with given name was not found

References toolbarNames.

QStringList gui::Menu::getToolbarList ( )

Return list of toolbar names

Returns:: Toolbar list

void gui::Menu::invalidItem	(	const QString &	type,
		const QString &	name,
		const QString &	line,
		const QString &	expected = `QString::null`
	)			throw (InvalidMenuException) `[static]`

Exit with error message after encountering invalid menu/toolbar item

Parameters:

	type	Type of offending item
	name	Name of offending item
	line	Line with offending item
	expected	Optional "Expected" field hinting what is expected to make data valid

bool gui::Menu::isList ( const QString & line ) [static]

Check if menu item with given definition is a list

Parameters:

line

Definition of the item to check

Returns:: true if menu is a list

Referenced by gui::QSMenu::addItem(), and gui::QSMenu::QSMenu().

void gui::Menu::loadItem	(	const QString &	name,
		QMenuData *	parent = `NULL`,
		QStringList	prev = `QStringList()`
	)			throw (InvalidMenuException)

Load one menu item and insert it into parent menu. Recursively load subitems if item is a submenu.

Parameters:

	name	name of item to be loaded from config file
	parent	parent menu item. If NULL and the item is list, the item is loaded in cache, but not added anywhere
	prev	String list containing names of all parents of this menu item (used for loop detection)

Referenced by gui::QSMenu::addItem().

void gui::Menu::loadItems	(	const QString &	name,
		QMenuData *	menu,
		QStringList	prev = `QStringList()`
	)			throw (InvalidMenuException) `[private]`

Load all needed items into existing menu list

Parameters:

	name	name of item to be loaded from config file
	menu	menu in which to load items (menu bar or popup menu)
	prev	String list containing names of all parents of this menu item (used for loop detection)

void gui::Menu::loadItemsDef	(	QString	line,
		QMenuData *	menu,
		QStringList	prev = `QStringList()`
	)			throw (InvalidMenuException) `[private]`

Load all needed items into existing menu list

Parameters:

	line	comma separated list of childs
	menu	menu in which to load items (menu bar or popup menu)
	prev	String list containing names of all parents of this menu item (used for loop detection)

QMenuBar * gui::Menu::loadMenu ( QWidget * parent ) throw (InvalidMenuException)

Loads menubar from configuration bar, and return it
If menubar can't be loaded, InvalidMenuException will be thrown Missing menu icons are allowed (if it can't be loaded, there will be no pixmap), missing items in configuration are not.

Parameters:

parent

QWidget that will contain the menubar

Returns:: loaded and initialized menubar

ToolBar * gui::Menu::loadToolbar	(	const QString &	name,
		bool	visible = `true`
	)			throw (InvalidMenuException) `[private]`

Load single toolbar from configuration file

Parameters:

	name	Toolbar name in configuration file
	visible	Will be toolbar initially visible?

Returns:: loaded toolbar

void gui::Menu::loadToolBarItem	(	ToolBar *	tb,
		const QString &	item
	)			throw (InvalidMenuException) `[private]`

Load single toolbar item and add it to toolbar

Parameters:

	tb	Toolbar for addition of item
	item	Item name in configuration file

ToolBarList gui::Menu::loadToolBars ( ) throw (InvalidMenuException)

Load all toolbars from configuration files and add them to parent window If toolbar can't be loaded, InvalidMenuException will be thrown

QString gui::Menu::menuItemText	(	const QString &	caption,
		const QString &	name
	)			`[private]`

Return item text for given menu item Will translate the text

Parameters:

	caption	Caption of the menu item
	name	Name if the menu item

Returns:: localized item text

void gui::Menu::optimizeItems ( QMenuData * menu ) [private]

Add accelerator to items that do not have one

Parameters:

menu

Menu to process

References util::explode(), and gui::MENULIST_SEPARATOR.

QString gui::Menu::parseName	(	QString &	line,
		const QString &	name = `QString::null`
	)			throw (InvalidMenuException) `[static]`

Parse name of list or item from line. List is then modified to contain only list of its items, or in case if item the rest of parameters

Parameters:

	line	Line with menu list definition
	name	Name (key) of this menu item (for locatization)

Returns:: localized caption of the menu item

Referenced by gui::QSMenu::addItemDef(), and gui::QSMenu::QSMenu().

QString gui::Menu::pop	(	QStringList::ConstIterator &	it,
		const QStringList::ConstIterator &	end
	)			`[static]`

Get first string from QStringList iterator and advance iterator one item further. Return QString::null if at ending position "end"

Parameters:

	it	iterator
	end	iterator marking ending position

Returns:: currrent iterator item or QString::null if after the end

QString gui::Menu::readItem ( const QString & name ) throw (InvalidMenuException) [static]

Load one GUI item from config file, exiting application with fatal error if item not found

Parameters:

name

Name of the item to read

Returns:: line from config file

Referenced by gui::QSMenu::addItem(), and gui::QSMenu::QSMenu().

bool gui::Menu::reserveAccel	(	const QString &	accelDef,
		const QString &	action
	)			`[private]`

Add accelerator to list of used accelerators and return true, if the accelerator was not taken before. Ensure only one item uses the accelerator at time

Parameters:

	accelDef	Accelerator in string form
	action	Action to reserve for this accelerator

Returns:: true if accelerator was not in list before, false otherwise

void gui::Menu::restoreToolbars ( )

Restore toolbar state of QMainWindow from configuration

void gui::Menu::saveToolbars ( )

Save toolbar state of QMainWindow to configuration

References toolbarList.

void gui::Menu::setTextByName	(	const QString &	name,
		const QString &	newText
	)

Set text on toolbar or menu item with given name. If both text and menu item exist with same name, both are updated. Note: the text wilol be translated according to the translation file, so english text should be used and any translation should be put into the translation file

Parameters:

	name	Name of the item
	newText	text on the item

void gui::Menu::showByName	(	const QString &	name,
		bool	show
	)

Show or hide item in toolbar, given its name.
Items in menu can't be show or hidden this way

Parameters:

	name	Name of item
	show	True to show, false to hide

QString gui::Menu::toolTipText	(	const QString &	text,
		const QString &	name,
		QString	accel = `QString::null`
	)			`[private]`

Return tooltip text for given text Will translate the tooltip, remove any & characters that have meaning in menus and add accelerator if specified

Parameters:

	text	Tooltip text
	name	Name of the toolbar item for which the text is. Used for correctly determining possible translation
	accel	Accelerator specified for the item (or QString::null if none defined or unknown)