Устройство файлов ресурсов в VGUI2

From Valve Developer Community
Jump to: navigation, search
English

Введение

Я стал свидетелем большого замешательства, когда спросил других программистов, как система VGUI2 взаимодействует с файлами ресурсов, и я не нашел полной справки по их использованию, так что вот.

Что они делают

Файлы ресурсов используются для автоматического создания элементов управления (= панелей), которые можно поместить в родительский элемент управления. Таким образом, сделать макет панели намного проще. Следовательно, файлы ресурсов очень удобны, когда вы создаете собственную внутриигровую панель и хотите, чтобы тяжелый подъем макета выполнялся автоматически.

Примечание:Файлы ресурсов не имеют ничего общего с (автоматическим) созданием новых «типов» элементов управления: они просто дайджест того, какие элементы управления размещаются, где и как они инициализируются.

Дизайн

Файлы ресурсов представляют собой простые KeyValues, которые анализируются сверху вниз: каждый элемент управления, указанный в файле, создается с помощью фабрики элементов управления, и его настройки применяются в иерархическом порядке..

При создании новой внутриигровой панели

Загрузка .res файла

Чтобы загрузить файл ресурсов для панели, просто добавьте в конструктор следующее:

LoadControlSettings( "Path/To/Resource/File.res" );

Настройка управления в игре

Смотрите The VGUI Build Mode чтобы получить больше информации.

Изменение элементов управления, сгенерированных файлом ресурсов, в коде

Допустим, вы создали свою собственную панель и поместили несколько ImagePanels в файл ресурсов. Если вы хотите изменить автоматически созданный элемент управления, вам нужно сделать только несколько вещей:

  • Создайте указатель для элемента управления в файле заголовка:
vgui::ImagePanel* m_pTestImage;
  • Заполните элемент управления в своем конструкторе:
m_pTestImage = dynamic_cast<ImagePanel*>( FindChildByName( "NameOfPanelInResourceFile", true ) );

Если вы используете Source SDK 2013, вы можете вместо этого использовать более короткий метод шаблона.:

m_pTestImage = FindControl<ImagePanel>( "NameOfPanelInResourceFile", true );
Предупреждение:Убедитесь, что вы вызываете эту строку после загрузки файла ресурсов, иначе вы всегда получите обратно NULL-указатель!
  • Готово! Теперь вы можете получить доступ к ImagePanel (не забудьте проверить нулевые указатели!)

Не беспокойтесь о необходимости очистки автоматически созданных панелей; они делают это сами.

При создании нового типа контроля

Завод (с утра на него)

Системе необходимо знать, какие элементы управления можно создать с использованием заводского метода. Это необходимо для автоматического создания элементов управления при чтении файла ресурсов. Для этого используется следующий макрос:

DECLARE_BUILD_FACTORY( Label );

This method will attempt to create an instance of the control with a constructor with two parameters, which are both NULL:

#define DECLARE_BUILD_FACTORY( className )										\
	static vgui::Panel *Create_##className##( void )							\
		{																		\
			return new className( NULL, NULL );									\
		};																		\
		static vgui::CBuildFactoryHelper g_##className##_Helper( #className, Create_##className## );\
	className *g_##className##LinkerHack = NULL;

Если вы хотите передать другие параметры или у вас есть параметры, не допускающие значения NULL, для которых требуется значение по умолчанию, вы можете использовать DECLARE_BUILD_FACTORY_CUSTOM:

// Example: ComboBoxNew inherits from ComboBox

// Custom ComboBoxNew method
vgui::Panel *ComboBoxNew_Factory()
{
	return new ComboBoxNew( NULL, NULL, 5, true );
}

// Принимает имя класса и имя метода. Убедитесь, что метод определен перед этой строкой!
DECLARE_BUILD_FACTORY_CUSTOM( ComboBoxNew, ComboBoxNew_Factory );

Применение настроек

Метод ApplySettings( KeyValues* inResourceData ) это то, что делает тяжелый подъем при выкладывании вашего контроля. Из-за иерархической структуры элементов управления (A наследуется от B, B наследуется от C и т. Д.) Очень легко создать новый элемент управления, конкретные настройки которого могут управляться данными (то есть инициализироваться из файла ресурсов). Вот пример:

Скажите, что ваш элемент управления, 'ImagePanelBetter' , наследуется от 'ImagePanel' . Затем вы переопределите виртуальную функцию 'ApplySettings ()' и прочтите что-нибудь для своего контроля:

void ImagePanelBetter::ApplySettings(KeyValues *inResourceData)
{
	// VERY IMPORTANT: ALWAYS CALL THE BASE CLASS!
	BaseClass::ApplySettings( inResourceData );

	const char *value = NULL;
	value = inResourceData->GetString("normalImage", "");
	if (*value)
		UpdateNormalImage( value );

	value = inResourceData->GetString("mouseoverImage", "");
	if (*value)
		UpdateMouseOverImage( value );

	value = inResourceData->GetString("mouseclickImage", "");
	if (*value)
		UpdateMouseClickImage( value );

	value = inResourceData->GetString("command", "");
	if (*value)
		UpdateCommand( value );
}

Довольно просто, не так ли?

Поскольку файлы ресурсов представляют собой просто KeyValues, вы также можете вкладывать элементы:

void ImagePanelBetter::ApplySettings(KeyValues *inResourceData)
{
	// VERY IMPORTANT: ALWAYS CALL THE BASE CLASS!
	BaseClass::ApplySettings( inResourceData );

	KeyValues* nestedItem;
	nestedItem = inResourceData->FindKey( "NameOfNestedItemInResourceFile" );
	if (nestedItem )
		DoStuff( nestedItem );
}

Иерархический обзор ключей в файлах ресурсов

Это обзор того, какие ключи определены в коде и каковы их функции.

Панель

Описание: Простой элемент управления, который является основой для всех других элементов управления VGUI. Содержит множество переопределяемых функций.

Наследуется от: None

  • fieldName: Определяет имя элемента управления.
  • xpos: Определяет горизонтальное смещение от верхнего левого угла (по умолчанию) родительской панели.
  • ypos; Определяет вертикальное смещение от верхнего левого угла (по умолчанию) родительской панели.
  • wide: Определяет ширину элемента управления.
  • tall: Определяет высоту элемента управления.
Совет:
Вы можете применить смещение к этим четырем переменным положения / размера с помощью флага положения или размера.
  • zpos: Определяет глубину панели. Сначала рисуются более глубокие панели. Меньшие числа = глубже.
  • visible: Определяет, будет ли отображаться элемент управления.
Совет:
Любые элементы управления, у которых этот элемент управления является родительским, также будут скрыты / показаны.
  • enabled: Определяет, включен ли элемент управления. Используется элементами управления выше по цепочке (например, кнопками).
  • tabPosition: Определяет порядок табуляции элемента управления.
  • tooltip:rutext: Определяет текст всплывающей подсказки, отображаемый при наведении курсора на этот элемент управления.
  • paintbackground: Нарисуйте цвет фона этого элемента управления?

Есть также ряд переопределяемых цветов, определенных в нескольких элементах управления. Panel проверяет себя и своих дочерних элементов и имеет следующие определения:

  • fgcolor_override: Переопределяет цвет переднего плана (для надписей это цвет текста).
  • bgcolor_override: Переопределяет цвет фона.
Совет:
Запишите значения цвета следующим образом: "R G B A" or "ColorNameInScheme". Пример: "fgcolor_override" "255 0 0 255" or "fgcolor_override" "My.Custom.Color"


Label

Описание: Элемент управления, который может отображать (переносить) текст.

Наследуется от: Panel

  • labelText: Определяет текст, который будет отображаться на метке.
Совет:
Помещение текста между знаком процента сделает его локализованной переменной. Например, строка % test% создаст локализованную строкуg #var_test. Смотрите VGUI Localization для получения дополнительной информации о локализованных строках.
Совет:
Вы также можете просто назначить неизменяемую локализованную строку, добавив знак управления, # перед строкой: #test будет искать в списке токенов, а локализованный текст будет отображаться на его месте.
  • textAlignment: Определяет выравнивание метки.
Совет:
Допустимые значения: north-west, north, north-east, west, center, east, south-west, south and south-east.
  • associate: Позволяет связать метку с другим элементом управления. To do: Посмотрите, для чего это нужно.
  • dulltext: Логическое значение, определяющее, должен ли текст отображаться скучно.
  • brighttext: Логическое значение, определяющее, должен ли текст отображаться ярко.
Совет:
У вас может быть только один из этих двух активных. Выбирается тот, который определен первым.
  • font: Определяет шрифт, используемый меткой. Используйте имя шрифта, как определено в файле SourceScheme.res.
  • wrap: Определяет, охватывает ли Ваш Label доступное пространство.
  • centerwrap: То же, что и выше, за исключением того, что это также работает для центрированного текста.
  • textinsetx: Дополнительное пространство смещения по горизонтали с какой бы стороны оно ни было выровнено.
  • textinsety: Дополнительное пространство вертикального смещения с какой бы стороны оно ни было выровнено.

Кнопка

Описание: Элемент управления, который может отображать (переносить) текст и действовать как кнопка.

Наследуется от: Label

  • command: Определяет, какая команда запускается в обработчике OnCommand при нажатии.
  • default: Логическое значение, определяющее, должна ли эта кнопка активироваться, когда пользователь нажимает клавиши Enter или пробела. Может существовать только одна такая кнопка.
  • selected: Логическое значение, определяющее, была ли выбрана эта кнопка.
  • sound_armed: Определяет, какой звук издает кнопка при наведении курсора.
  • sound_depressed: Определяет, какой звук издает кнопка при нажатии.
  • sound_released: Определяет, какой звук будет издавать кнопка при отпускании.

ImagePanel

Описание: По сути, образ.

Наследуется от: Panel

  • scaleImage: Логическое значение, определяющее, масштабировать ли изображение до указанной ширины и высоты.
  • scaleAmount: Поплавок, определяющий масштаб изображения.
  • tileImage: Логическое значение, определяющее, размещать ли изображение мозаикой.
  • tileHorizontally: Логическое значение, определяющее, размещать ли изображение мозаикой по горизонтали.
  • tileVertically: Логическое значение, определяющее, размещать ли изображение вертикально.
  • image: Tреальное изображение. Ожидает путь к файлу .VMT в папке /materials/vgui.
Совет:
Пример: допустим, что ваш файл .VMT называется example1.vmt и расположен в /materials/vgui/examples, тогда путь, который вы должны указать здесь, будет examples/example1».
Совет:
Подтверждено на компьютере с Windows - Вы можете перейти по папке вверх, включив ../ в путь к файлу. Например, чтобы получить доступ к example.vmt в /materials/images, используйте ../images/example в качестве пути.
  • fillcolor: Определяет цвет фона за изображением. Окрашивается, только если альфа больше 0 (да)
Совет:
Вы можете указать цвет как в формате RGBA, так и обратиться к цвету в файлах схемы, просто указав его имя в качестве значения.
  • border: Определяет границу вокруг изображения. Вы можете ссылаться только на цвета, определенные в файлах схемы, используя названия цветов!

EditablePanel

Описание: Окно-подобный элемент управления, который может содержать другие элементы управления, которые можно редактировать с помощью VGUI Build Mode.

Наследуется от: Panel

Frame

Описание: Элемент управления с динамически изменяемым размером, который можно перетаскивать. Имеет строку заголовка, кнопки закрытия и сворачивания и т.Д.

Наследуется от: EditablePanel

Note:элемент управления Frame имеет приоритет над ключом "visible", определенным в Panel.
  • title: Определяет заголовок кадра.
  • title_font: Определяет, какой шрифт будет использоваться в заголовке фрейма.
  • clientinsetx_override: Переопределяет горизонтальное смещение по умолчанию от левой стороны панели.

Цвет отменяет:

  • infocus_bgcolor_override: Переопределить цвет фона панели, когда она находится в фокусе.
  • outoffocus_bgcolor_override: Переопределить цвет фона панели, когда она не в фокусе.
  • titlebarbgcolor_override: Переопределение цвета фона строки заголовка, когда она находится в фокусе.
  • titlebardisabledbgcolor_override: Переопределение цвета фона строки заголовка, когда она не в фокусе.
  • titlebarfgcolor_override: Переопределение цвета переднего плана строки заголовка, когда она находится в фокусе.
  • titlebardisabledfgcolor_override: Переопределить цвет переднего плана строки заголовка, когда он не в фокусе.

To do: Это ещё не конец!