File indexing completed on 2024-04-28 05:45:03
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2022 Felix Ernst <felixernst@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0006 */ 0007 0008 #ifndef KFILEITEMLISTTOSTRING_H 0009 #define KFILEITEMLISTTOSTRING_H 0010 0011 class KFileItemList; 0012 class QFontMetrics; 0013 class QString; 0014 0015 enum ItemsState { None, Selected }; 0016 0017 /** 0018 * @brief Generates a textual representation of the given list of KFileItems. 0019 * 0020 * This method is especially useful to be very explicit about which items will be affected by an action. 0021 * For example can a label for a delete button be enriched to say "Permanantly Delete `picture1` and `picture2`" 0022 * but also "Permanently Delete 7 Selected Folders" without requiring a huge amount of new translations for this. 0023 * 0024 * Unfortunately this doesn't always work. 0025 * 0026 * For some texts and some languages this wide range of words cannot be inserted into a text while staying 0027 * grammatically correct. Because of this you will probably need to write a fallback for these languages. 0028 * Something like this: 0029 * \code 0030 * // i18n: @action:inmenu menu with actions like copy, paste, rename. 0031 * // %2 is a textual representation of the currently selected files or folders. This can be the name of 0032 * // the file/files like "file1" or "file1, file2 and file3" or an aggregate like "8 Selected Folders". 0033 * // If this sort of word puzzle can not be correctly translated in your language, translate it as "NULL" (without the quotes) 0034 * // and a fallback will be used. 0035 * 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)); 0036 * if (buttonText == QStringLiteral("NULL")) { 0037 * buttonText = i18ncp("@action Delete button label. %1 is the number of items to be deleted.", 0038 * "Permanently Delete %1 Item", "Permanently Delete %1 Items", items.count()) 0039 * } 0040 * \endcode 0041 * (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 ) 0042 * 0043 * @param items The KFileItemList for which a QString should be generated. 0044 * @param maximumTextWidth The maximum width/horizontalAdvance the QString should have. Keep scaling in mind. 0045 * @param fontMetrics the fontMetrics for the font that is used to calculate the maximumTextWidth. 0046 * @param itemsState A state of the @p items that should be spelled out in the returned QString. 0047 * @returns the names of the @p items separated by commas if that is below the @p maximumCharacterWidth. 0048 * Otherwise returns something like "5 Files", "8 Selected Folders" or "60 Items" 0049 * while being as specific as possible. 0050 */ 0051 QString fileItemListToString(KFileItemList items, int maximumTextWidth, const QFontMetrics &fontMetrics, ItemsState itemsState = ItemsState::None); 0052 0053 #endif // KFILEITEMLISTTOSTRING_H