digiKam Developer Documentation: Digikam::ContextMenuHelper Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Types | Signals | Public Member Functions | List of all members
Digikam::ContextMenuHelper Class Reference

A helper class to add actions and special menus to the context menu. More...

Inheritance diagram for Digikam::ContextMenuHelper:

## Public Types
typedef const QList< qlonglong > | imageIds

## Signals
void | signalAddNewTagFromABCMenu (const QString &)
void | signalAddToExistingQueue (int)
void | signalAssignColorLabel (int)
void | signalAssignPickLabel (int)
void | signalAssignRating (int)
void | signalAssignTag (int)
void | signalCreateGroup ()
void | signalCreateGroupByFilename ()
void | signalCreateGroupByTime ()
void | signalCreateGroupByTimelapse ()
void | signalGotoAlbum (const ItemInfo &)
void | signalGotoDate (const ItemInfo &)
void | signalGotoTag (int)
void | signalPopupTagsView ()
void | signalRemoveFromGroup ()
void | signalRemoveTag (int)
void | signalSetThumbnail (const ItemInfo &)
void | signalUngroup ()

## Public Member Functions
| ContextMenuHelper (QMenu *const parent)
| Constructs the helper class.
void | addAction (const QString &name, bool addDisabled=false)
| Add an action from the actionCollection.
void | addAction (QAction *const action, bool addDisabled=false)
| Add a temporary action.
void | addAction (QAction *const action, QObject *const recv, const char *const slot, bool addDisabled=false)
| Add a temporary action and assign it to a custom slot.
void | addActionDeleteAlbum (AlbumModificationHelper *const helper, PAlbum *const album)
void | addActionDeleteFaceTag (TagModificationHelper *const helper, TAlbum *const tag)
| Add action to delete tags from people sidebar.
void | addActionDeleteFaceTags (TagModificationHelper *const helper, const QList< TAlbum * > &tags)
void | addActionDeleteTag (TagModificationHelper *const helper, TAlbum *const tag)
void | addActionDeleteTags (TagModificationHelper *const helper, const QList< TAlbum * > &tags)
void | addActionEditAlbum (AlbumModificationHelper *const helper, PAlbum *const album)
void | addActionEditTag (TagModificationHelper *const helper, TAlbum *const tag)
void | addActionNewAlbum (AlbumModificationHelper *const helper, PAlbum *const parentAlbum=nullptr)
| Add actions to add, remove or edit a tag.
void | addActionNewTag (TagModificationHelper *const helper, TAlbum *const parentTag=nullptr)
| Add actions to add, remove or edit a tag.
void | addActionRenameAlbum (AlbumModificationHelper *const helper, PAlbum *const album)
void | addActionResetAlbumIcon (AlbumModificationHelper *const helper, PAlbum *const album)
void | addActionTagsToFaceTags (TagModificationHelper *const helper, const QList< TAlbum * > &tags)
void | addActionTagToFaceTag (TagModificationHelper *const helper, TAlbum *const tag)
| Add action to set tags as face tags.
void | addAlbumCheckUncheckActions (Album *const album)
| Add a Select and Deselect menu to check and uncheck albums.
void | addAssignTagsMenu (const imageIds &ids)
| Add "Assign Tags" menu.
void | addCreateTagFromAddressbookMenu ()
| Add a menu to create new tags from adressbook entries.
void | addExportMenu ()
| Add Export Webservices actions menu.
void | addGotoMenu (const imageIds &ids)
| Add the Goto menu.
void | addGroupActions (const imageIds &ids)
void | addGroupMenu (const imageIds &ids, const QList< QAction * > &extraMenuItems=QList< QAction * >())
| Add a "Group" menu.
void | addImportMenu ()
| Add Import Webservices actions menu.
void | addIQSAction (QObject *const recv, const char *const slot)
| Add the standard Image Quality Sorter action and connect it to the appropriate slot.
void | addLabelsAction ()
| Add "Pick/Color/Rating Labels" action.
void | addOpenAndNavigateActions (const imageIds &ids, bool lightTable=false)
| Add section for main views for opening and moving/going to albums.
void | addQueueManagerMenu ()
| Add Queue Manager actions menu.
void | addRemoveAllTags (const imageIds &ids)
| Add "Remove all Tags" action.
void | addRemoveTagsMenu (const imageIds &ids)
| Add "Remove Tags" menu.
void | addSeparator ()
| Add a separator to the context menu.
void | addServicesMenu (const QList< QUrl > &selectedItems)
| Add the services menu to the menu.
void | addStandardActionCopy (QObject *const recv, const char *const slot)
| Add the standard copy action and connect it to the appropriate slot.
void | addStandardActionCut (QObject *const recv, const char *const slot)
| Add the standard cut action and connect it to the appropriate slot.
void | addStandardActionItemDelete (QObject *const recv, const char *const slot, int quantity=1)
| Add the standard delete action and connect it to the appropriate slot.
void | addStandardActionLightTable ()
| Add the lighttable action to the menu.
void | addStandardActionPaste (QObject *const recv, const char *const slot)
| Add the standard paste action and connect it to the appropriate slot.
void | addStandardActionThumbnail (const imageIds &ids, Album *const album)
| Add the thumbnail action to the menu.
void | addSubMenu (QMenu *subMenu)
| Add a submenu to the parent context menu.
QAction * | exec (const QPoint &pos, QAction *const at=nullptr)
| Execute the registered parent menu and evaluate the triggered actions.
void | setAlbumModel (AbstractCheckableAlbumModel *const model)
| Set an album model.
void | setItemFilterModel (ItemFilterModel *const model)
| Set a filter model.

## Detailed Description

The ContextMenuHelper class helps adding commonly used actions and menus. Use this class to add

- actions from the actionCollection
- standard actions (copy, paste, delete)
- temporary actions
- predefined special actions
- predefined submenus to the menu.

All addAction() methods take a special parameter 'addDisabled'. This parameter controls if disabled actions are added to the menu. Normally adding disabled actions is turned off, to clean up the menu and make it more readable.

If the ContextMenuHelper class is used, you need to call its own exec() method, instead the one from the parent menu. This way signals from special menus can be emitted and connected to the appropriate slots.

## Constructor & Destructor Documentation

## ◆ ContextMenuHelper()

Digikam::ContextMenuHelper::ContextMenuHelper | ( | QMenu *const | parent | ) |
| explicit

Parameters

  parent | the menu the helper class is linked to

## Member Function Documentation

## ◆ addAction() [1/3]

void Digikam::ContextMenuHelper::addAction | ( | const QString & | name,
|  | bool | addDisabled = `false`
| ) |  |

This method adds actions from the actionCollection. The actionCollection can be set in the constructor of the ContextMenuHelper class.

Parameters

  name | the name of the action in the actionCollection
  addDisabled | if set, disabled actions are added to the menu

## ◆ addAction() [2/3]

void Digikam::ContextMenuHelper::addAction | ( | QAction *const | action,
|  | bool | addDisabled = `false`
| ) |  |

Sometimes it is necessary to define actions that only exist in the current context menu content. Use this method to add such an action.

Parameters

  action | the action to add
  addDisabled | if set, disabled actions are added to the menu

## ◆ addAction() [3/3]

void Digikam::ContextMenuHelper::addAction | ( | QAction *const | action,
|  | QObject *const | recv,
|  | const char *const | slot,
|  | bool | addDisabled = `false`
| ) |  |

Use this method if you want to add a temporary action and immediately connect it to the receiving slot.

Parameters

  action | the action to add
  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to
  addDisabled | if set, disabled actions are added to the menu

## ◆ addActionNewAlbum()

void Digikam::ContextMenuHelper::addActionNewAlbum | ( | AlbumModificationHelper *const | helper,
|  | PAlbum *const | parentAlbum = `nullptr`
| ) |  |

The tag modification helper is used to execute the action. You must set the parent tag to use on modification helper.

## ◆ addActionNewTag()

void Digikam::ContextMenuHelper::addActionNewTag | ( | TagModificationHelper *const | helper,
|  | TAlbum *const | parentTag = `nullptr`
| ) |  |

The tag modification helper is used to execute the action. You must set the parent tag to use on modification helper.

## ◆ addAlbumCheckUncheckActions()

void Digikam::ContextMenuHelper::addAlbumCheckUncheckActions | ( | Album *const | album | ) |

Note: Call setAlbumModel before, or this will have no effect.

## ◆ addAssignTagsMenu()

void Digikam::ContextMenuHelper::addAssignTagsMenu | ( | const imageIds & | ids | ) |

This menu will provide a list of all tags available so that they can be assigned to the current selected items.

To make this menu work, you need to run exec() from this class, otherwise the signals are not emitted and you will not be able to react on triggered actions from this menu. Make sure to connect the signals to the appropriate slots in the context menu handling method.

Parameters

  ids | the selected items

See also
  exec()
  signalAssignTag()

## ◆ addGotoMenu()

void Digikam::ContextMenuHelper::addGotoMenu | ( | const imageIds & | ids | ) |

This menu will provide the following actions for the given item:

- Goto Album
- Goto Date
- Goto Tag To make this menu work, you need to run exec() from this class, otherwise the signals are not emitted and you will not be able to react on triggered actions from this menu. Make sure to connect the signals to the appropriate slots in the context menu handling method.

Parameters

  ids | the list of selected items

See also
  exec()
  signalGotoAlbum() signalGotoDate() signalGotoTag()

TODO:tags to be ported to multiple selection

## ◆ addGroupMenu()

void Digikam::ContextMenuHelper::addGroupMenu | ( | const imageIds & | ids,
|  | const QList< QAction * > & | extraMenuItems = `QList<QAction*>()`
| ) |  |

This menu will provide actions open, close, add to, remove from, or split a group.

addGroupActions will add the actions as a flat list, not in a submenu. Note: Call setItemFilterModel before to have Open/Close group actions.

## ◆ addIQSAction()

void Digikam::ContextMenuHelper::addIQSAction | ( | QObject *const | recv,
|  | const char *const | slot
| ) |  |

Parameters

  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to

## ◆ addLabelsAction()

void Digikam::ContextMenuHelper::addLabelsAction | ( |  | ) |

This action will provide methods to assign pick/color/rating labels to the currently selected items.

To make this menu work, you need to run exec() from this class, otherwise the signals are not emitted and you will not be able to react on triggered actions from this menu. Make sure to connect the signals to the appropriate slots in the context menu handling method.

See also
  exec()
  signalAssignPickLabel()
  signalAssignColorLabel()
  signalAssignRating()

## ◆ addOpenAndNavigateActions()

void Digikam::ContextMenuHelper::addOpenAndNavigateActions | ( | const imageIds & | ids,
|  | bool | lightTable = `false`
| ) |  |

This is a convenience function to ensure consistent menus and reduce code duplication.

Parameters

  ids | the list of selected items
  lightTable | for the light table

## ◆ addRemoveAllTags()

void Digikam::ContextMenuHelper::addRemoveAllTags | ( | const imageIds & | ids | ) |

Removes all tags from the selected item ids except face tags.

Parameters

  ids | the selected items

## ◆ addRemoveTagsMenu()

void Digikam::ContextMenuHelper::addRemoveTagsMenu | ( | const imageIds & | ids | ) |

This menu will provide a list of all tags assigned to the current items. Actions triggered in here will remove the selected tag from the items.

To make this menu work, you need to run exec() from this class, otherwise the signals are not emitted and you will not be able to react on triggered actions from this menu. Make sure to connect the signals to the appropriate slots in the context menu handling method.

Parameters

  ids | the selected items

See also
  exec()
  signalRemoveTag()

## ◆ addServicesMenu()

void Digikam::ContextMenuHelper::addServicesMenu | ( | const QList< QUrl > & | selectedItems | ) |

The services menu is used to open the selected items in a different application. It will query the item for registered services and provide them in a submenu. The menu will be titled "Open With...".

Parameters

  selectedItems | the list of selected items

## ◆ addStandardActionCopy()

void Digikam::ContextMenuHelper::addStandardActionCopy | ( | QObject *const | recv,
|  | const char *const | slot
| ) |  |

Parameters

  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to

## ◆ addStandardActionCut()

void Digikam::ContextMenuHelper::addStandardActionCut | ( | QObject *const | recv,
|  | const char *const | slot
| ) |  |

Parameters

  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to

## ◆ addStandardActionItemDelete()

void Digikam::ContextMenuHelper::addStandardActionItemDelete | ( | QObject *const | recv,
|  | const char *const | slot,
|  | int | quantity = `1`
| ) |  |

Parameters

  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to
  quantity | the number of the files that should be deleted. This parameter is used for the action name and is normally used when deleting more then one item.

## ◆ addStandardActionLightTable()

void Digikam::ContextMenuHelper::addStandardActionLightTable | ( |  | ) |

Do not use addAction() to add the lighttable action, because we need to handle special cases here. Depending on whether the lighttable window has already been created and filled with items, we set different actions.

## ◆ addStandardActionPaste()

void Digikam::ContextMenuHelper::addStandardActionPaste | ( | QObject *const | recv,
|  | const char *const | slot
| ) |  |

Parameters

  recv | the receiver of the triggered action
  slot | the slot to connect the triggered action to

## ◆ addStandardActionThumbnail()

void Digikam::ContextMenuHelper::addStandardActionThumbnail | ( | const imageIds & | ids,
|  | Album *const | album
| ) |  |

Do not use addAction() to add the thumbnail action, because we need to handle special cases here. Depending on whether the current view is album or icon view, we set different actions.

Parameters

  ids | the selected items in the current view
  album | the current album the AlbumIconView is displaying

## ◆ addSubMenu()

void Digikam::ContextMenuHelper::addSubMenu | ( | QMenu * | subMenu | ) |

Parameters

  subMenu | the submenu to be added

## ◆ exec()

QAction * Digikam::ContextMenuHelper::exec | ( | const QPoint & | pos,
|  | QAction *const | at = `nullptr`
| ) |  |

Always use this method instead the one from the parent menu. It will ensure that the signals are emitted and special cases are handled.

Parameters

  pos | position of the triggered action in the registered menu
  at | the action that should be at the position pos

Returns
  the triggered action

## ◆ setAlbumModel()

void Digikam::ContextMenuHelper::setAlbumModel | ( | AbstractCheckableAlbumModel *const | model | ) |

The check/uncheck actions will operate directly on the model.

## ◆ setItemFilterModel()

void Digikam::ContextMenuHelper::setItemFilterModel | ( | ItemFilterModel *const | model | ) |

Some of the group actions will operate directly on the model.