В этом разделе перечислены свойства и методы объекта JCJS_ini плагина PluginSetting
new JCJS_ini() Создать объект
// Загрузить плагин и Установить в JS конструторы объектов
post.loadPlugin('PluginSetting').install(scriptEngine);
// Создать объект
var ini = new JCJS_ini();
Отсутствуют
Отсутствуют
int ini.setFilename(String) Функция
Открыть файл настроек
var iniFile = server.parseSpecialFileName("stuff@Lesav/sql-akrb08/akrb.ini");
var res = ini.setFilename(iniFile);
switch(res)
{
case 0: post.log('i', 'Файл ' + iniFile + ' успешно открыт');
case -1: post.log('e', 'Файл ' + iniFile + ' не найден');
case 1: post.log('e', 'Произошла ошибка доступа (например, попытка записи в файл только для чтения)');
case 2: post.log('e', 'Произошла ошибка формата (например, загрузка повреждённого INI-файла)');
}
String ini.getFileName() Функция
Прочесть имя открытого файла
var iniFile = ini.getFileName();
bool ini.isWritable() Функция
Возвращает true, если настройки могут быть сохранены с помощью объекта JCJS_ini;
в противном случае возвращает false.
Одной из причин, почему ini.isWritable() может вернуть false, является то,
что JCJS_ini работает с файлом только для чтения.
Предупреждение: Эта функция не является абсолютно надёжной,
так как права доступа могут измениться в любой момент.
void ini.clear() Процедура
Удаляет все записи в основном расположении, связанном с объектом JCJS_ini.
Записи в альтернативных расположениях не удаляются.
Если вы хотите удалить только записи в текущей группе group(), то используйте вместо этого remove("").
ini.clear();
void ini.sync() Процедура
Записывает любые несохранённые данные в постоянное хранилище и перезагружает
любые настройки, которые были к тому времени изменены другим приложением.
Эта функция вызывается автоматически из деструктора JCJS_ini и регулярно
в цикле событий, так что вам обычно не требуется вызывать её самостоятельно.
ini.sync();
int ini.status() Функция
Возвращает код состояния, указывающий первую ошибку, которая встретилась JCJS_ini,
или 0, если ошибок не было.
Помните, что JCJS_ini откладывает выполнение некоторых операций.
По этой причине перед вызовом status() вам может потребоваться вызвать sync()
для гарантии того, что сохранённые в JCJS_ini данные записаны на диск.
var res = ini.status();
switch(res)
{
case 0: post.log('i', 'Выполнено успешно');
case 1: post.log('e', 'Произошла ошибка доступа (например, попытка записи в файл только для чтения)');
case 2: post.log('e', 'Произошла ошибка формата (например, загрузка повреждённого INI-файла)');
}
void ini.beginGroup(String prefix) Процедура
Добавляет префикс prefix к текущей группе.
Текущая группа автоматически добавляется в начало всех ключей, определяемых JCJS_ini.
Кроме того, функции запросов, такие как ini.childGroups(), ini.childKeys() и ini.allKeys(),
основываются на группе. По умолчанию группа не установлена.
Группы могут быть использованы для того, чтобы избежать ввода
раз за разом одних и тех же путей настроек. Например:
settings.beginGroup("mainwindow");
settings.setValue("size", win.size());
settings.setValue("fullScreen", win.isFullScreen());
settings.endGroup();
settings.beginGroup("outputpanel");
settings.setValue("visible", panel.isVisible());
settings.endGroup();
Это позволит установить значения трёх настроек:
Вызовите ini.endGroup() для сброса текущей группы к состоянию перед вызовом ini.beginGroup().
Группы могут быть вложенными.
void ini.endGroup() Процедура
Сбрасывает группу к той, какой она была до соответствующего вызова ini.beginGroup().
ini.beginGroup("alpha");
// ini.group() == "alpha"
ini.beginGroup("beta");
// ini.group() == "alpha/beta"
ini.endGroup();
// ini.group() == "alpha"
ini.endGroup();
// ini.group() == ""
String ini.group() Функция
Возвращает текущую группу.
var gr = ini.group();
int ini.beginReadArray( String prefix ) Функция
Добавляет префикс prefix к текущей группе и начинает читать из массива. Возвращает размер массива.
var logins = [];
var size = ini.beginReadArray("logins");
for (var i = 0; i < size; ++i) {
ini.setArrayIndex(i);
var login = {};
login.userName = ini.value("userName");
login.password = ini.value("password");
logins.push(login);
}
ini.endArray();
void ini.beginWriteArray(String prefix, size = -1) Процедура
Добавляет префикс prefix к текущей группе и начинает запись массива размером size.
Если размер size равен -1 (по умолчанию), то он определяется
автоматически на основании индексов записываемых записей.
Если у вас есть множество вхождений определённого набора ключей,
то вы можете упростить свою жизнь, используя массивы.
Например, давайте предположим, что вы хотите сохранить массив имён пользователей и паролей переменной длины.
Тогда вы можете написать:
var logins = [];
...
ini.beginWriteArray("logins");
for (int i = 0; i < logins.size(); ++i) {
ini.setArrayIndex(i);
ini.setValue("userName", logins[i].userName);
ini.setValue("password", logins[i].password);
}
ini.endArray();
Сгенерированные ключи будут иметь вид
void ini.endArray() Процедура
Заканчивает массив, начатый при помощи ini.beginReadArray() или ini.beginWriteArray().
void ini.setArrayIndex(i) Процедура
Устанавливает текущий индекс массива в i.
Вызовы таких функций, как ini.setValue(), ini.value(), ini.remove() и ini.contains(),
будут оперировать с записью массива с этим индексом.
Перед вызовом этой функции вы должны вызвать ini.beginReadArray() или ini.beginWriteArray().
arr[String] ini.allKeys() Функция
Возвращает список всех ключей, включая подключи, которые могут быть прочитаны с помощью объекта JCJS_ini.
ini.setValue("fridge/color", 'white');
ini.setValue("fridge/size", '32x96');
ini.setValue("sofa", true);
ini.setValue("tv", false);
var keys = ini.allKeys();
// keys: ["fridge/color", "fridge/size", "sofa", "tv"]
Если с помощью ini.beginGroup() установлена группа, то возвращаются только ключи в группе, без префикса группы:
ini.beginGroup("fridge");
keys = ini.allKeys();
// keys: ["color", "size"]
arr[String] ini.childKeys() Функция
Возвращает список всех ключей верхнего уровня, которые могут быть прочитаны с помощью объекта JCJS_ini.
ini.setValue("fridge/color", 'white');
ini.setValue("fridge/size", '32x96');
ini.setValue("sofa", true);
ini.setValue("tv", false);
var keys = ini.allKeys();
// keys: ["sofa", "tv"]
Если с помощью ini.beginGroup() установлена группа, то возвращаются только ключи верхнего уровня, без префикса группы:
ini.beginGroup("fridge");
keys = ini.allKeys();
// keys: ["color", "size"]
arr[String] ini.childGroups() Функция
Возвращает список всех ключей групп верхнего уровня, содержащих ключи, которые могут быть прочитаны с помощью объекта JCJS_ini.
ini.setValue("fridge/color", 'white');
ini.setValue("fridge/size", '32x96');
ini.setValue("sofa", true);
ini.setValue("tv", false);
var groups = ini.childGroups();
// group: ["fridge"]
Если с помощью ini.beginGroup() установлена группа, то возвращаются только ключи верхнего уровня в группе, без префикса группы.
ini.beginGroup("fridge");
var groups = ini.childGroups();
// groups: []
void ini.setValue(key, value) Процедура
Устанавливает значение настройки key в значение value.
Если key уже существует, то предыдущее значение перезаписывается.
Заметьте, что реестр Windows и INI-файлы используют нечувствительные к регистру ключи,
в то время как Carbon Preferences API в Mac OS X использует чувствительные к регистру ключи.
Variant ini.value(key, defaultValue) Функция
Возвращает значение для настройки key. Если настройка не существует,
то возвращает значение по умолчанию defaultValue.
Если значение по умолчанию не указано, то по умолчанию будет возвращён Variant.
Заметьте, что реестр Windows и INI-файлы используют нечувствительные к регистру ключи,
в то время как Carbon Preferences API в Mac OS X использует чувствительные к регистру ключи.
void ini.remove(key) Процедура
Удаляет настройку key и любые вложенные в key настройки.
ini.setValue("ape");
ini.setValue("monkey", 1);
ini.setValue("monkey/sea", 2);
ini.setValue("monkey/doe", 4);
ini.remove("monkey");
var keys = ini.allKeys();
// keys: ["ape"]
Имейте в виду, что если в одном из альтернативных расположений содержится
настройка с тем же ключом, то настройка будет видна после remove().
Если key является пустой строкой, то удаляются все ключи текущей группы group(). Например:
ini.setValue("ape");
ini.setValue("monkey", 1);
ini.setValue("monkey/sea", 2);
ini.setValue("monkey/doe", 4);
ini.beginGroup("monkey");
ini.remove("");
ini.endGroup();
var keys = ini.allKeys();
// keys: ["ape"]
Заметьте, что реестр Windows и INI-файлы используют нечувствительные к регистру ключи,
в то время как Carbon Preferences API в Mac OS X использует чувствительные к регистру ключи.
bool ini.contains(key) Функция
Возвращает true, если существует настройка с названием key; в противном случае возвращает false.
Если с помощью ini.beginGroup() установлена группа, то ключ key берётся по отношению к этой группе.
bool ini.fallbacksEnabled() Функция
Возвращает true, если механизм альтернативы включён; в противном случае возвращает false.
По умолчанию механизм альтернативы включён.
void ini.setFallbacksEnabled(b) Процедура
Устанавливает, включен/выключает механизм альтернативы.
По умолчанию механизм альтернативы включён.
int ini.format() Функция
Возвращает формат, используемый для сохранения настроек.
В Unix NativeFormat и IniFormat означают одно и то же, за исключение того, что различается расширение файла (.conf для NativeFormat, .ini для IniFormat).
Формат файла INI является форматом файла Windows, который поддерживается Qt на всех платформах.
В отсутствии стандарта на INI мы пытаемся следовать тому, что делает Microsoft, за исключением следующего:
Если вы сохраняете тип, который QVariant не может преобразовать в QString (например, QPoint, QRect и QSize),
то Qt использует @-основанный синтаксис для кодирования типа. Например:
Для минимизации проблем совместимости любые @, которые появляются не в первой позиции значения
или за которыми не следует тип Qt (Point, Rect, Size и т.д.), обрабатываются как обычные символы.
Несмотря на то, что обратная наклонная черта является специальным символом в INI-файлах,
большинство приложений Windows не экранируют обратную наклонную черту (\) в путях файлов:
JCJS_ini всегда обрабатывает обратную наклонную черту как специальный символ
и предоставляет API для чтения и записи таких элементов.
Формат файла INI имеет серьёзные ограничения на синтаксис ключа.
Qt обходит их, используя % как экранирующий символ в ключах. В дополнение, если вы сохраняете
настройку верхнего уровня (ключ без наклонных черт в нём, например, "someKey"),
то он появится в INI-файле в разделе "General". Чтобы избежать перезаписи других ключей,
если вы сохраняете что-то, используя такие ключи, как "General/someKey", ключ будет размещён
в разделе "%General", а не в разделе "General".
Следуя философии, что мы должны быть либеральными в том, что мы принимаем, и консервативными в том,
что мы формируем, JCJS_ini будет принимать INI-файлы, закодированные в Latin-1,
а формировать чистые ASCII-файлы, где не-ASCII-значения кодируются, используя
стандартные escape-последовательности INI. Для того чтобы INI-файлы были более читаемыми
(но потенциально менее совместимыми), вызовите ini.setCodec().
int ini.scope() Функция
Возвращает область действия, используемую для сохранения настроек.
void setSystemIniPath(String dir) Процедура
void setUserIniPath(String dir) Процедура
Устанавливает путь, используемый для сохранения настроек
В таблице ниже обобщены значения по умолчанию:
| Платформа | Формат | Scope | Path |
|---|---|---|---|
| Windows | IniFormat | UserScope | %APPDATA% |
| SystemScope | %COMMON_APPDATA% | ||
| Unix | NativeFormat, IniFormat | UserScope | $HOME/.config |
| SystemScope | /etc/xdg | ||
| Qt для встраиваемых Linux-систем | NativeFormat, IniFormat | UserScope | $HOME/Settings |
| SystemScope | /etc/xdg | ||
| Mac OS X | IniFormat | UserScope | $HOME/.config |
| SystemScope | /etc/xdg |
void ini.setCodec(String codec) Процедура
Установить при необходимости декодер строк при работе с файлом
ini.setCodec('windows-1251');
/*
==== Список поддерживаемых кодеков (включая синонемы) ===
UTF-8 ISO-8859-1 latin1 CP819
IBM819 iso-ir-100 csISOLatin1 ISO-8859-15
latin9 UTF-32LE UTF-32BE UTF-32
UTF-16LE UTF-16BE UTF-16 System
roman8 hp-roman8 csHPRoman8 TIS-620
ISO 8859-11 WINSAMI2 WS2 Apple Roman
macintosh MacRoman windows-1258 CP1258
windows-1257 CP1257 windows-1256 CP1256
windows-1255 CP1255 windows-1254 CP1254
windows-1253 CP1253 windows-1252 CP1252
windows-1251 CP1251 windows-1250 CP1250
IBM866 CP866 csIBM866 IBM874
CP874 IBM850 CP850 csPC850Multilingual
ISO-8859-16 iso-ir-226 latin10 ISO-8859-14
iso-ir-199 latin8 iso-celtic ISO-8859-13
ISO-8859-10 iso-ir-157 latin6 ISO-8859-10:1992
csISOLatin6 ISO-8859-9 iso-ir-148 latin5
csISOLatin5 ISO-8859-8 ISO 8859-8-I iso-ir-138
hebrew csISOLatinHebrew ISO-8859-7 ECMA-118
greek iso-ir-126 csISOLatinGreek ISO-8859-6
ISO-8859-6-I ECMA-114 ASMO-708 arabic
iso-ir-127 csISOLatinArabic ISO-8859-5 cyrillic
iso-ir-144 csISOLatinCyrillic ISO-8859-4 latin4
iso-ir-110 csISOLatin4 ISO-8859-3 latin3
iso-ir-109 csISOLatin3 ISO-8859-2 latin2
iso-ir-101 csISOLatin2 KOI8-U KOI8-RU
KOI8-R csKOI8R Iscii-Mlm Iscii-Knd
Iscii-Tlg Iscii-Tml Iscii-Ori Iscii-Gjr
Iscii-Pnj Iscii-Bng Iscii-Dev TSCII
GB18030 GBK GB2312 CP936
MS936 windows-936 EUC-JP ISO-2022-JP
Shift_JIS JIS7 SJIS MS_Kanji
EUC-KR cp949 Big5 Big5-HKSCS
Big5-ETen CP950
*/