src/kitemviews/kfileitemlisttostring.h

   1 /*
   2     This file is part of the KDE project
   3     SPDX-FileCopyrightText: 2022 Felix Ernst <felixernst@zohomail.eu>
   4
   5     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
   6 */
   7
   8 #ifndef KFILEITEMLISTTOSTRING_H
   9 #define KFILEITEMLISTTOSTRING_H
  10
  11 class KFileItemList;
  12 class QFontMetrics;
  13 class QString;
  14
  15 enum ItemsState {
  16     None,
  17     Selected
  18 };
  19
  20 /**
  21  * @brief Generates a textual representation of the given list of KFileItems.
  22  *
  23  * This method is especially useful to be very explicit about which items will be affected by an action.
  24  * For example can a label for a delete button be enriched to say "Permanantly Delete `picture1` and `picture2`"
  25  * but also "Permanently Delete 7 Selected Folders" without requiring a huge amount of new translations for this.
  26  *
  27  * Unfortunately this doesn't always work.
  28  *
  29  * For some texts and some languages this wide range of words cannot be inserted into a text while staying
  30  * grammatically correct. Because of this you will probably need to write a fallback for these languages.
  31  * Something like this:
  32  * \code
  33  * // i18n: @action:inmenu menu with actions like copy, paste, rename.
  34  * // %2 is a textual representation of the currently selected files or folders. This can be the name of
  35  * // the file/files like "file1" or "file1, file2 and file3" or an aggregate like "8 Selected Folders".
  36  * // If this sort of word puzzle can not be correctly translated in your language, translate it as "NULL" (without the quotes)
  37  * // and a fallback will be used.
  38  * auto buttonText = i18ncp("@action A more elaborate and clearly worded version of the Delete action", "Permanently Delete %2", "Permanently Delete %2", items.count(), fileItemListToString(items, fontMetrics.averageCharWidth() * 20, fontMetrics));
  39  * if (buttonText == QStringLiteral("NULL")) {
  40  *      buttonText = i18ncp("@action Delete button label. %1 is the number of items to be deleted.",
  41  *              "Permanently Delete %1 Item", "Permanently Delete %1 Items", items.count())
  42  * }
  43  * \endcode
  44  * (The i18n call should be completely in the line following the i18n: comment without any line breaks within the i18n call or the comment might not be correctly extracted. See: https://commits.kde.org/kxmlgui/a31135046e1b3335b5d7bbbe6aa9a883ce3284c1 )
  45  *
  46  * @param items The KFileItemList for which a QString should be generated.
  47  * @param maximumTextWidth The maximum width/horizontalAdvance the QString should have. Keep scaling in mind.
  48  * @param fontMetrics the fontMetrics for the font that is used to calculate the maximumTextWidth.
  49  * @param itemsState A state of the @p items that should be spelled out in the returned QString.
  50  * @returns the names of the @p items separated by commas if that is below the @p maximumCharacterWidth.
  51  *          Otherwise returns something like "5 Files", "8 Selected Folders" or "60 Items"
  52  *          while being as specific as possible.
  53  */
  54 QString fileItemListToString(KFileItemList items, int maximumTextWidth, QFontMetrics fontMetrics, ItemsState itemsState = ItemsState::None);
  55
  56 #endif // KFILEITEMLISTTOSTRING_H