View source for Interface modding

{{Version|Timeless}}
在《钢铁雄心IV》中，接口是指玩家用来与游戏交互的用户界面。

== 概述 ==
接口文件的组件可以分为两组：容器和元素。例如，''containerWindowType'' 是一个容器，而 ''iconType'' 是一个元素。

接口文件使用 .gui 文件类型。 所有接口文件都可以在 {{path|interface/}} 中找到。

当出现 ''internal''  字样时，这个部分的源代码是只有P社可以修改的，即它所指的主题是不可修改的。

== 宏 ==
可以在界面文件中使用宏，以便更轻松地调整位置。 

例如，这将使一个名为 WINDOW_X_POS 的宏，其值为 10。
<pre>@WINDOW_X_POS = 10</pre>

可以在元素中这样引用它：
<pre>
containerWindowType = {
    name = "my_container"
    position = { x = @WINDOW_X_POS y = -600 }

    # ...
}
</pre>

== 容器 ==
容器用于将元素组合在一起，并将它们与内部函数相关联。 

除非通过[[Scripted GUI modding|脚本化 GUI，]]否则无法添加新容器。这是因为容器的 ''name'' 属性在内部链接到容器所需的任何数据。常见的例外是，您可以在 ''countrytechtreeview.gui'' 中为自定义技术文件夹添加新容器。

容器定义的顺序和嵌套会影响它们的显示方式。 

== containerWindowType ==
最常见的容器类型，用于保存任何一组元素。

通常使用以下属性：
* '''name''' - 容器的名称。
* '''background''' - 容器的背景。
* '''position''' - 容器的屏幕位置。
* '''size''' - 容器的边界框。接受百分数( 如 100%% )。
* '''moveable''' - 设置是否可以拖动容器。
* '''fullscreen''' -设置是否将容器全屏化。
* '''orientation''' - 设置 ''position'' 属性的方向原点。
* '''clipping''' - 设置容器是否将修剪其他元素（如在边界处剪切其元素）。

以下属性用于动画容器：
* '''show_position''' - 容器在''显示''模式下移动到的屏幕位置。
* '''hide_position''' - 容器在''隐藏''模式下移动到的屏幕位置。
* '''show_animation_type''' - The animation type used to show the container (always ''decelerated'').用于显示容器的动画类型（始终''减速）''。
* '''hide_animation_type''' - The animation type used to hide the container (always ''accelerated'').用于隐藏容器的动画类型（始终''加速）。''
* '''animation_time''' - 动画播放时间（始终''为 300''）。
* '''upsound''' - 当容器移动到''显示''位置时要播放的声音。
* '''downsound''' - 当容器移动到''隐藏''位置时要播放的声音。
* '''fade_time''' - 淡入淡出的时间。
* '''fade_type''' - 淡入的类型（始终为''线性''）。

以下属性很少或从不使用：
* '''dontRender''' - 不渲染
* '''horizontalBorder''' - 水平边界
* '''verticalBorder''' - 垂直边界

== scrollbarType ==
滚动条类型用于定义滚动条由哪些元素组成。

使用以下属性：
* '''name''' - 滚动条名称。
* '''slider''' - 用作滚动条滑块的按钮元素。
* '''track''' - 用作滚动条跟踪器的按钮元素。
* '''leftbutton''' - 用作滚动条左增量按钮的按钮元素。
* '''rightbutton''' - 用作滚动条右增量按钮的按钮元素。
* '''position''' - 滚动条的屏幕位置。
* '''size''' - 滚动条的边界框。
* '''priority''' - 滚动条相对于其他元素的优先级。
* '''borderSize''' - 滚动条边框的边界框。
* '''maxValue''' - 滚动条能移动的最大值（用于控制增量）。
* '''minValue''' - 滚动条能移动的最小值（用于控制增量）。
* '''stepSize''' - 使用增量按钮的单次增量大小。
* '''startValue''' - 滚动条滑块的初始大小。
* '''horizontal''' - 设置滚动条是水平 （1） 还是垂直 （0）。

== Elements ==
容器中使用了多种元素类型。所有元素都必须在容器内使用，它们不会在容器之外工作。

元素将继承它们所在的容器的方向，除非为自己指定了方向。

以下元素可以自由添加，并可用于脚本化 GUI。
* '''iconType''' - 用于静态图像。
* '''instantTextBoxType''' - 用于文本。
* '''buttonType''' - 用于按钮。

以下元素依赖于内部代码。您可以添加新元素，它们不会填充数据。
* '''smoothListboxType''' - 用于平滑滚动列表。
* '''listboxType''' - 用于滚动列表。
* '''checkboxType''' - 用于复选框。
* '''OverlappingElementsBoxType''' - 用于重叠元素。
* '''editBoxType''' - 用于可编辑的文本框。
* '''shieldtype''' - 用于显示国家/地区旗帜。

以下元素已过时：
* '''guiButtonType''' - 与 ''buttonType'' 相同。
* '''textBoxType''' -与 ''instantTextBoxType'' 相同。
* '''eu3dialogtype''' - 与 ''windowType'' 相同。
* '''shieldtype''' - 仅在 ''eu3dialogtype'' 中使用。 较新的文件中的标志使用不同的元素。

== iconType ==
The ''iconType'' element is used to add images to the interface. It's usage overlaps with ''buttonType'', which is similar but operates as a button.

The following attributes are used:
* '''name''' - The icon name.
* '''position''' - The screen position of the icon.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''spriteType''' - The image to use for the icon. Refers to a ''spriteType'' definition.
* '''quadTextureSprite''' - The image to use for the icon. Refers to a dynamic ''spriteType'' definitions (i.e. flags) or multi-frame ''spriteType'' definitions.
* '''frame''' - Which frame to use for the icon when using a multi-frame image.
* '''alwaystransparent''' - Forces the icon to allow click through, i.e. clicking on an element behind another element.
* '''hint_tag''' - Set the hint key the icon uses to display a hint tooltip with when hovered over.
* '''pdx_tooltip''' - Sets the tooltip to display to the player. Takes a localization key.
* '''pdx_tooltip_delayed''' - Sets the delayed tooltip to display to the player. Takes a localization key.
* '''centerposition''' - Sets whether the position is from the center of the icon.

== instantTextBoxType ==
The ''instantTextBoxType'' element is used to add text to the interface. In some instances, the text for the element is generated internally (i.e. ''regiment_count''). In these instances you cannot edit the text unless it is exposed in an localized string.

The following attributes are used:
* '''name''' - The textbox name.
* '''position''' - The screen position of the textbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''text''' - The text displayed by the textbox.
* '''font''' - The font to use for the text.
* '''maxWidth''' - The total width in pixels at which text is displayed.
* '''maxHeight''' - The total height in pixels at which text is displayed.
* '''format''' - How the text is aligned. 
* '''fixedsize''' - Whether the textbox should truncate text that exceeds its limits.
* '''borderSize''' - The bounding box for the border of the textbox.
* '''alwaystransparent''' - Forces the text to allow click through, i.e. clicking on an element behind another element.
* '''pdx_tooltip''' - Sets the tooltip to display to the player. Takes a localization key.
* '''pdx_tooltip_delayed''' - Sets the delayed tooltip to display to the player. Takes a localization key.

The following attributes are rarely or never used:
* '''textureFile''' - Never used for anything.

Valid ''format'' values:
* left
* centre
* right

== buttonType ==
The ''guiButtonType''' element is used to add buttons to the interface. Buttons are composed of an image and text, so they operate in a similar manner to ''iconType'' and ''instantTextBoxType''.

The following attributes are used:
* '''name''' - The button name.
* '''position''' - The screen position of the button.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''spriteType''' - The image to use for the button. Refers to a ''spriteType'' definition.
* '''quadTextureSprite''' - The image to use for the button. Refers to a dynamic ''spriteType'' definitions (i.e. flags) or multi-frame ''spriteType'' definitions.
* '''frame''' - Which frame to use for the button when using a multi-frame image.
* '''alwaystransparent''' - Forces the button to allow click through, i.e. clicking on an element behind another element.
* '''buttonText''' - The text displayed by the button. 
* '''buttonFont''' - The font to display the button text in.
* '''shortcut''' - The shortcut to add for this button.
* '''clicksound''' - The sound to use when clicked.
* '''oversound''' - The sound to play when hovered over.
* '''hint_tag''' - Set the hint key the icon uses to display a hint tooltip with when hovered over.
* '''pdx_tooltip''' - Sets the tooltip to display to the player. Takes a localization key.
* '''pdx_tooltip_delayed''' - Sets the delayed tooltip to display to the player. Takes a localization key.
* '''scale''' - Scales the button size.

The following attributes are rarely or never used:
* '''tooltip''' - Never used.
* '''tooltipText''' - Never used.
* '''delayedTooltipText''' - Never used.

== smoothListboxType ==
The ''smoothListboxType'' element is used to define a listbox, which is a scrollable list that is populated with entries. Typically these elements are internally linked with another container, which composes the actual entry used in the list box.

The following attributes are used:
* '''name''' - The listbox name.
* '''position''' - The screen position of the listbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''size''' - The bounding box for the listbox.
* '''spacing''' - The spacing to use between listbox entries.
* '''horizontal'' - Whether the listbox is horizontal (1) or vertical (0).
* '''scrollbartype''' - The scrollbar to use for the listbox.
* '''bordersize''' - The bounding box for the border for the listbox.
* '''alwaystransparent''' - Forces the listbox to allow click through, i.e. clicking on an element behind another element.

The following attributes are rarely or never used:
* '''background''' - Never used.

== listboxType ==
The ''listboxType '' element is used to define a listbox, which is a scrollable list that is populated with entries. Typically these elements are internally linked with another container, which composes the actual entry used in the list box.

The following attributes are used:
* '''name''' - The listbox name.
* '''position''' - The screen position of the listbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''size''' - The bounding box for the listbox.
* '''spacing''' - The spacing to use between listbox entries.
* '''horizontal'' - Whether the listbox is horizontal (1) or vertical (0).
* '''scrollbartype''' - The scrollbar to use for the listbox.
* '''bordersize''' - The bounding box for the border for the listbox.
* '''alwaystransparent''' - Forces the listbox to allow click through, i.e. clicking on an element behind another element.

The following attributes are rarely or never used:
* '''background''' - Never used.

== checkboxType ==
The ''checkboxType '' element is used to add checkboxes to the interface. The actual effect of the checkbox is defined internally.

The following attributes are used:
* '''name''' - The checkbox name.
* '''position''' - The screen position of the checkbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''spriteType''' - The image to use for the checkbox. Refers to a ''spriteType'' definition.
* '''quadTextureSprite''' - The image to use for the checkbox. Refers to a dynamic ''spriteType'' definitions (i.e. flags) or multi-frame ''spriteType'' definitions.
* '''frame''' - Which frame to use for the checkbox when using a multi-frame image.
* '''alwaystransparent''' - Forces the checkbox to allow click through, i.e. clicking on an element behind another element.
* '''buttonText''' - The text displayed by the checkbox. 
* '''buttonFont''' - The font to display the checkbox text in.
* '''shortcut''' - The shortcut to add for this checkbox.
* '''clicksound''' - The sound to use when clicked.
* '''hint_tag''' - Set the hint key the checkbox uses to display a hint tooltip with when hovered over.
* '''pdx_tooltip''' - Set the short tooltip this checkbox uses. 
* '''pdx_tooltip_delayed''' - Set the full tooltip this checkbox uses. 
* '''scale''' - Scales the checkbox size.

The following attributes are rarely or never used:
* '''tooltip''' - Never used.
* '''tooltipText''' - Never used.
* '''delayedTooltipText''' - Never used.

== editBoxType ==
The ''editBoxType'' element is used to add editable textboxes to the interface.

The following attributes are used:
* '''name''' - The textbox name.
* '''position''' - The screen position of the textbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''text''' - The text displayed by the textbox.
* '''font''' - The font to use for the text.
* '''maxWidth''' - The total width in pixels at which text is displayed.
* '''maxHeight''' - The total height in pixels at which text is displayed.
* '''format''' - How the text is aligned. 
* '''fixedsize''' - Whether the textbox should truncate text that exceeds its limits.
* '''borderSize''' - The bounding box for the border of the textbox.
* '''alwaystransparent''' - Forces the text to allow click through, i.e. clicking on an element behind another element.
* '''ignore_tab_navigation''' - Makes the element ignore tab navigation.

== OverlappingElementsBoxType ==
The ''OverlappingElementsBoxType'' element is used to define a special kind of listbox that dynamically overlaps sub-elements within itself. 

The following attributes are used:
* '''name''' - The listbox name.
* '''position''' - The screen position of the listbox.
* '''orientation''' - Sets the orientation origin for the ''position'' attribute.
* '''size''' - The bounding box for the listbox.
* '''spacing''' - The spacing to use between listbox entries.
* '''horizontal'' - Whether the listbox is horizontal (1) or vertical (0).
* '''bordersize''' - The bounding box for the border for the listbox.
* '''alwaystransparent''' - Forces the listbox to allow click through, i.e. clicking on an element behind another element.

The following attributes are rarely or never used:
* '''textureFile''' - Never used for anything.

Valid ''format'' values:
* left
* centre
* right

== Position and Orientation ==
Understanding how the position coordinates work is important to understanding how to edit interfaces correctly. 

The ''orientation'' attribute used by an element (or container) informs you where the anchor point for the element is. For example, ''UPPER_LEFT'' means the ''( 0, 0 )'' position is in the top left corner of the screen, whereas ''LOWER_RIGHT'' is the bottom right.

The ''position'' attribute then works from this origin position. Therefore if you want an element to be on the opposite side of the screen, you'd want to change the ''orientation'' first.

This is system is used because it allows the interface to adapt to different resolutions. Because all positions are tied to a specific origin that is dynamically calculated from the player's screen resolution, the placement of containers and elements are kept consistent. 

So, if you want to ensure your interface edits are consistent, you must use the ''orientation'' attribute properly. 

An mistake would be to edit the ''position'' solely, for example <code>position = { x = 1800 y = 200 }</code>. This would look fine for anybody with a screen width greater than 1800px (i.e. 1900 x 1200 upwards), but the element would be off screen for those with smaller screens.

Valid ''orientation'' values (can be upper or lowercase):
* CENTER
* UPPER_LEFT
* LOWER_LEFT
* UPPER_RIGHT
* LOWER_RIGHT

== Fonts ==
''See also: [[Font modding]]''

The following fonts are usable in Hearts of Iron IV:
* Arial12
* Arial12_bold
* cg_16b
* cg_18b
* garamond_12
* garamond_14
* garamond_14_bold
* garamond_16
* garamond_16_bold
* garamond_24
* hoi_16mbs
* hoi_16tooltip3
* hoi_16typewriter
* hoi_18
* hoi_18b
* hoi_18mbs
* hoi_20b
* hoi_20bs
* hoi_22tech
* hoi_22typewriter
* hoi_24header
* hoi_26mbs
* hoi_30header
* hoi_33
* hoi_36header
* hoi4_typewriter16
* hoi4_typewriter22
* hoi_mapfont4
* hoi_arrow_font
* newsfeed_body
* newsfeed_title
* standard
* standard_18
* standard_22
* tahoma_20_bold
* vic_18
* vic_18_grey
* vic_18s
* vic_22
* vic_22_bl
* vic_22s
* vic_36
* vic_36s


{{Modding navbox}}
[[Category:Modding]]