- Joined
- Jul 18, 2010
- Messages
- 2,377
Table of Contents
Requirements
If you don't know how to use a custom toc-File, therefore can't use a custom fdf you should first do a tutorial about toc: UI: toc-Files.
Introduction
SimpleFrames are another group of frames. They are low in amount of types but frames of this group manage most of the direct ingame UI, like the unitinfo, the ability and item buttons.
Unlike Frames, Simpleframes require fdf and can not be created in a useful way without such a fdf defining a SimpleFrame first. All SimpleFrames can be moved out of the 4:3 screen. Most custom created Simpleframes do not fight for mousecontrol. For the displaying SimpleFrames are below Frames.
If I write SIMPLEFRAME in uppercase only, i talk about this specific type otherwise i address the group.
Unlike Frames, Simpleframes require fdf and can not be created in a useful way without such a fdf defining a SimpleFrame first. All SimpleFrames can be moved out of the 4:3 screen. Most custom created Simpleframes do not fight for mousecontrol. For the displaying SimpleFrames are below Frames.
If I write SIMPLEFRAME in uppercase only, i talk about this specific type otherwise i address the group.
SimpleFrame Types
The mainframe able types in warcraft 3 for Simpleframes:
SIMPLEBUTTON
SIMPLECHECKBOX
SIMPLEFRAME
SIMPLESTATUSBAR
They are defined in the fdf like Frames are. The start of 2 such Simpleframe definitions.
SIMPLEBUTTON
SIMPLECHECKBOX
SIMPLEFRAME
SIMPLESTATUSBAR
They are defined in the fdf like Frames are. The start of 2 such Simpleframe definitions.
Code:
Frame "SIMPLEFRAME" "SimpleInfoPanelIconDamage" {...
Frame "SIMPLEBUTTON" "UpperButtonBarButtonTemplate" {...Special Children
SimpleFrames have 2 special frame-types which can not be real mainframes. During the game this types can only exist as children of any Simpleframe.
String
Texture
This 2 types are Simpleframes, means one can use the frame natives onto them. But their definition differs from the others, inside fdf.
Inside the game this frames would be accessed with:
BlzGetFrameByName("SimpleInfoPanelTitleTextDisabledTemplate", createcontext)
BlzGetFrameByName("InfoPanelIconBackdrop", createcontext)
Inside a fdf, such String/Texture can be defined outside of Simpleframes to have a base to inherit from. But one can create them only as part of a Simpleframe during the game.
String
Texture
This 2 types are Simpleframes, means one can use the frame natives onto them. But their definition differs from the others, inside fdf.
Code:
String "SimpleInfoPanelTitleTextDisabledTemplate" INHERITS "SimpleInfoPanelTitleTextTemplate" {...
Texture "InfoPanelIconBackdrop" INHERITS "InfoPanelIconTemplate" {...BlzGetFrameByName("SimpleInfoPanelTitleTextDisabledTemplate", createcontext)
BlzGetFrameByName("InfoPanelIconBackdrop", createcontext)
Inside a fdf, such String/Texture can be defined outside of Simpleframes to have a base to inherit from. But one can create them only as part of a Simpleframe during the game.
Warning
The game does not like it, if you use this frame natives onto String/Texture, it will crash the game:
BlzFrameSetVisible
BlzFrameIsVisible
BlzFrameSetAlpha
BlzFrameSetLevel
BlzFrameSetVisible
BlzFrameIsVisible
BlzFrameSetAlpha
BlzFrameSetLevel
Anchor
SimpleFrames have another keyword to pos child frames Anchor. Anchor is a shortcut for: "SetPoint pointA, parent, pointA, x, y,". One can still use the other 2; SetPoint and SetAllPoints.
Anchor TOPLEFT, 0.1, 0.05,
pos the own TOPLEFT to the parents TOPLEFT with 0.1 x and 0.05 y offset.
Anchor as the others SetPoint require the attached frame to take a part of the screen by having atleast Width or Height or both.
Otherwise it can happen that the Texture/String attaches itself to the parent of the parent.
Without a point the String/Texture will center itself to the parent or that ones parent (which can be the 4:3 Screen when SimpleFrames are created for ORIGIN_FRAME_GAME_UI), if the direct parent fails.
Anchor TOPLEFT, 0.1, 0.05,
pos the own TOPLEFT to the parents TOPLEFT with 0.1 x and 0.05 y offset.
Anchor as the others SetPoint require the attached frame to take a part of the screen by having atleast Width or Height or both.
Otherwise it can happen that the Texture/String attaches itself to the parent of the parent.
Without a point the String/Texture will center itself to the parent or that ones parent (which can be the 4:3 Screen when SimpleFrames are created for ORIGIN_FRAME_GAME_UI), if the direct parent fails.
String
For Simpleframes String children display text onto the screen. One String can display one line of text or huge walls of text over multiple Lines, upto the whole screen and above that. I won't tell much about textmarkup for String, most is like with TEXT which should be an own subject.
It is recommented to create and place StringFrames at the earliest with the event "0s expired". At earlier times it can happen that the StringFrame is displaced or does not display any text until the user changes resolution.
String have a different keyword to setup the font then TEXT. Setting a font is required for a String to display visible text. There are 2 ways inside fdf to set Fonts either one adds DecorateFileNames, and uses for the fontFile a stringVariable from a StringList or write down the fontFile.
The FontFile also could be refered directly but without DecorateFileNames, in the parent. The example is not the same font.
It is recommented to create and place StringFrames at the earliest with the event "0s expired". At earlier times it can happen that the StringFrame is displaced or does not display any text until the user changes resolution.
String have a different keyword to setup the font then TEXT. Setting a font is required for a String to display visible text. There are 2 ways inside fdf to set Fonts either one adds DecorateFileNames, and uses for the fontFile a stringVariable from a StringList or write down the fontFile.
Font "InfoPanelTextFont",0.009,
InfoPanelTextFont is only valid with DecorateFileNames, , the font is required for the String to be displayed. DecorateFileNames, has to be written inside the Parent of the String, if one reads the font that way.The FontFile also could be refered directly but without DecorateFileNames, in the parent. The example is not the same font.
Font "fonts\nim_____.ttf", 0.009,
String Example
One defines a SIMPLEFRAME having a String child that childs shows the text.
In case you did skip Anchor the Width and Height are there to Anchor to the parent "TestString" which would fail otherwise.
The Lua code creating the SIMPLEFRAME from above and setting the text.
First some Debug text is printed so one knows the code is actually running at all. After that one loads the toc loading the fdf with the Simpleframe. Then the Simpleframe is created his point is set and the text of the String child is set.
Theoretically the font also could be set inside the code using BlzFrameSetFont. For some wierd reason that does not work for Frame Type "TEXT" (V1.31.1).
Using this font native with a fontsize differing much from the initial fontsize can break the displayed text.
In case you did skip Anchor the Width and Height are there to Anchor to the parent "TestString" which would fail otherwise.
Code:
Frame "SIMPLEFRAME" "TestString" {
Width 0.0001,
Height 0.0001,
DecorateFileNames,
String "TestStringValue" {
Anchor TOPLEFT, 0, 0,
Font "InfoPanelTextFont", 0.01,
}
}First some Debug text is printed so one knows the code is actually running at all. After that one loads the toc loading the fdf with the Simpleframe. Then the Simpleframe is created his point is set and the text of the String child is set.
Lua:
do
local real = MarkGameStarted
function MarkGameStarted()
real()
print("Start")
BlzLoadTOCFile("war3mapImported\\your.toc")
local parent = BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0)
local frame = BlzCreateSimpleFrame("TestString", parent, 0)
BlzFrameSetAbsPoint(frame, FRAMEPOINT_CENTER, 0.4, 0.5)
BlzFrameSetText(BlzGetFrameByName("TestStringValue", 0), "Test Text")
print("Done")
end
endTheoretically the font also could be set inside the code using BlzFrameSetFont. For some wierd reason that does not work for Frame Type "TEXT" (V1.31.1).
BlzFrameSetFont(stringFrame, "fonts\\dfst-m3u.ttf", 0.016, 0)BlzFrameSetFont(stringFrame, "fonts\\nim_____.ttf", 0.013, 0)BlzFrameSetFont(stringFrame, "fonts\\thowr___.ttf", 0.012, 0)Using this font native with a fontsize differing much from the initial fontsize can break the displayed text.
Texture
Texture is the visual part for Simpleframes (Images).
A Texture will if he does not have a own size copy the parent's size.
When seting the image inside the fdf one uses:
File FilePath,
Texture can have some configs:
A Texture can have an AlphaMode to change the usage of alpha/opaque.
Might look into a wow ui wiki for more infos, but be careful some might not work as expected or at all. The reason why one can look into wow is. Wow and warcraft 3 are both from Blizzard and they shared parts of their source code, part of it is the ui system.
When using BlzFrameSetTexture the AlphaMode is overwritten.
One can take only a fraction of an given image and display that to the space taken by the Texture, this affects the in fdf set image as by code. TextCoord has nothing to do with the space taken on the screen. TexCoord Left, Right, Up, Bottom
TexCoord 0, 1, 0, 0.125, (take the total x from 0 to 12.5% from the top of the Image-File)
TexCoord 0.0, 0.5, 0.0, 0.5, (the topLeft part) see image below only a fraction of the Paladin icon.
One can also produce a Tile using TextCoord, to fill the Frame's given screen space with copies of that image. This is also done with TexCoord, by giving numbers higher than 1 for right and bottom.
TexCoord 0, 2, 0, 2,
A Texture will if he does not have a own size copy the parent's size.
When seting the image inside the fdf one uses:
File FilePath,
Texture can have some configs:
A Texture can have an AlphaMode to change the usage of alpha/opaque.
AlphaMode "ALPHAKEY",
AlphaMode "ADD",
AlphaMode "DISABLE",
AlphaMode "BLEND",
AlphaMode "MOD",
AlphaMode "ADD",
AlphaMode "DISABLE",
AlphaMode "BLEND",
AlphaMode "MOD",
Might look into a wow ui wiki for more infos, but be careful some might not work as expected or at all. The reason why one can look into wow is. Wow and warcraft 3 are both from Blizzard and they shared parts of their source code, part of it is the ui system.
When using BlzFrameSetTexture the AlphaMode is overwritten.
One can take only a fraction of an given image and display that to the space taken by the Texture, this affects the in fdf set image as by code. TextCoord has nothing to do with the space taken on the screen. TexCoord Left, Right, Up, Bottom
TexCoord 0, 1, 0, 0.125, (take the total x from 0 to 12.5% from the top of the Image-File)
TexCoord 0.0, 0.5, 0.0, 0.5, (the topLeft part) see image below only a fraction of the Paladin icon.
One can also produce a Tile using TextCoord, to fill the Frame's given screen space with copies of that image. This is also done with TexCoord, by giving numbers higher than 1 for right and bottom.
TexCoord 0, 2, 0, 2,
A Texture can be rotated by 180 degree by placing TOPLEFT & TOPRIGHT in reversed positions (Topleft where Topright should be and Topright where TopLeft should be).
Texture example
Like with String this is an example how one would display just one Texture onto the screen. One defines a SIMPLEFRAME with Width and Height and a Texture which copies mimics the SIMPLEFRAME when not said otherwise.
We load the toc mentioning the fdf with the SIMPLEFRAME and create the mainFrame "TestTexture". After that set the texture of the child to the Icon of the Paladin and pos the SIMPLEFRAME to center of the screen.
Code:
Frame "SIMPLEFRAME" "TestTexture"{
Width 0.04,
Height 0.04,
Texture "TestTextureValue" {
}
}
Lua:
do
local real = MarkGameStarted
function MarkGameStarted()
real()
BlzLoadTOCFile("war3mapImported\\your.toc")
local frame = BlzCreateSimpleFrame("TestTexture", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 0)
BlzFrameSetTexture(BlzGetFrameByName("TestTextureValue", 0), "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin", 0, true)
BlzFrameSetAbsPoint(frame, FRAMEPOINT_CENTER, 0.4, 0.3)
end
endTexture Coloring
A Texture can be colored during the game with the native
When one uses that line onto an Archmage Texture it would become yellowish like that image below
Layer "BACKGROUND" {...
Layer "ARTWORK" {...
"ARTWORK" is displayed above "BACKGROUND".
The Layers of a SimpleFrame above, are both above a lower SimpleFrame.
Based on wow ui wikis there should be more, but I failed to create them. Probably they do not exist in warcraft 3 (V1.31.1). Theoretically one could think the HIGHLIGHT layer is implemented over the keyword UseHighlight <texture>, for SIMPLEBUTTON.
BlzFrameSetVertexColor takes framehandle frame, integer color. To get the color integer one uses another native BlzConvertColor takes integer a, integer r, integer g, integer bBlzFrameSetVertexColor(texture, BlzConvertColor(255, 255, 255, 1)) would display the texture without blue.When one uses that line onto an Archmage Texture it would become yellowish like that image below
Layer
Layer are a fdf feature for Simpleframes that can be used to set the order of String/Texture inside a SimpleFrame. Inside a Layer only String and Texture can be defined. Blizzard used 2 Layers in their fdf for warcraft 3.Layer "BACKGROUND" {...
Layer "ARTWORK" {...
"ARTWORK" is displayed above "BACKGROUND".
The Layers of a SimpleFrame above, are both above a lower SimpleFrame.
Based on wow ui wikis there should be more, but I failed to create them. Probably they do not exist in warcraft 3 (V1.31.1). Theoretically one could think the HIGHLIGHT layer is implemented over the keyword UseHighlight <texture>, for SIMPLEBUTTON.
Code:
Frame "SIMPLEFRAME" "TestTextureLayer" {
Width 0.1,
Height 0.1,
Layer "ARTWORK" {
Texture {
Width 0.05,
Height 0.05,
Anchor BOTTOMLEFT, 0, 0,
File "ReplaceableTextures\CommandButtons\BTNHeroMountainKing",
}
Texture {
Width 0.05,
Height 0.05,
Anchor BOTTOMRIGHT, 0, 0,
File "ReplaceableTextures\CommandButtons\BTNHeroBloodElfPrince",
}
}
Layer "BACKGROUND" {
Texture {
Width 0.1,
Height 0.1,
Anchor CENTER, 0, 0,
File "ReplaceableTextures\CommandButtons\BTNHeroPaladin",
}
}
}SIMPLEBUTTON
SimpleButton is the interactive Simpleframe. It is quite powerful for a Simpleframe, it can be clicked starting a FRAMEEVENT_CONTROL_CLICK, even when being moved out of the 4:3 Screen. When being clicked it will not keep the focus (which Frame-Buttons do). It controls the space on the screen, therefore one can not order/select units at that spot. Each SIMPLEBUTTON can have only one FRAMEEVENT_CONTROL_CLICK Event, when one registers another one (for the same SimpleButton) the previous event will not fire anymore.
Other Simpleframes can be the tooltip of a SIMPLEBUTTON (But the tooltip-SimpleFrame is not hidden with that call as it does with Frame, maybe a bug in 1.31.1).
One can use BlzFrameSetEnable on the Button to stop the user from starting events with that Buttons. But it will still control the screen space and the tooltip won't update anymore by (un)hovering the button. (Frame-Buttons stop controling the screenspace when being disabled, if they ever did)
Using BlzFrameSetVisible(button, false) will hide the button and it's children as it will free the screen space taken by them.
A SIMPLEBUTTON can have functional children to have a texture for different states and different Strings for that states. This functional children are kinda static and unreachable with BlzGetFrameByName, making them kinda bad for dynamic Icon Buttons. When one wants a Menu(F10) like Button then it is okay. "ui\framedef\ui\upperbuttonbar.fdf" contains blizzards usage for that. For an IconButton it is better to create a SIMPLEBUTTON with a Texture Child that way one can change the texture during the game.
This would be the definition for such an IconButton inside fdf:
During The game one would create with BlzCreateSimpleFrame "MySimpleButton" pos that frame and set the texture of "MySimpleButtonTexture" using BlzFrameSetTexture
The Lua code that creates that button showing a Paladin icon. When the button is clicked it prints "Button Click":
If one would want a glowing while the button is hovered, one would add the functional child frame to the SIMPLEBUTTON, inside the fdf. The example Highlight is the yellow glowing one sees in scorescreen.
Other Simpleframes can be the tooltip of a SIMPLEBUTTON (But the tooltip-SimpleFrame is not hidden with that call as it does with Frame, maybe a bug in 1.31.1).
One can use BlzFrameSetEnable on the Button to stop the user from starting events with that Buttons. But it will still control the screen space and the tooltip won't update anymore by (un)hovering the button. (Frame-Buttons stop controling the screenspace when being disabled, if they ever did)
Using BlzFrameSetVisible(button, false) will hide the button and it's children as it will free the screen space taken by them.
A SIMPLEBUTTON can have functional children to have a texture for different states and different Strings for that states. This functional children are kinda static and unreachable with BlzGetFrameByName, making them kinda bad for dynamic Icon Buttons. When one wants a Menu(F10) like Button then it is okay. "ui\framedef\ui\upperbuttonbar.fdf" contains blizzards usage for that. For an IconButton it is better to create a SIMPLEBUTTON with a Texture Child that way one can change the texture during the game.
This would be the definition for such an IconButton inside fdf:
Code:
Frame "SIMPLEBUTTON" "MySimpleButton" {
Width 0.039,
Height 0.039,
Texture "MySimpleButtonTexture" {
}
}The Lua code that creates that button showing a Paladin icon. When the button is clicked it prints "Button Click":
Lua:
do
local real = MarkGameStarted
function MarkGameStarted()
real()
BlzLoadTOCFile("war3mapImported\\MySimpleButton.toc")
local trigger = CreateTrigger()
TriggerAddAction(trigger, function()
print("Button Click")
-- SimpleButton does not keep the focus.
end)
local button = BlzCreateSimpleFrame("MySimpleButton", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 0)
BlzFrameSetAbsPoint(button, FRAMEPOINT_CENTER, 0.9, 0.3)
BlzFrameSetTexture(BlzGetFrameByName("MySimpleButtonTexture", 0), "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin", 0, true)
BlzTriggerRegisterFrameEvent(trigger, button, FRAMEEVENT_CONTROL_CLICK)
end
endIf one would want a glowing while the button is hovered, one would add the functional child frame to the SIMPLEBUTTON, inside the fdf. The example Highlight is the yellow glowing one sees in scorescreen.
Code:
Texture "MySimpleButtonButtonHighlight" {
File "UI\Glues\ScoreScreen\scorescreen-tab-hilight.blp",
AlphaMode "ADD",
}
Frame "SIMPLEBUTTON" "MySimpleButtonGlowing" {
Width 0.039,
Height 0.039,
UseHighlight "MySimpleButtonButtonHighlight",
Texture "MySimpleButtonTexture" {
}
}SIMPLESTATUSBAR was explained in another tutorial.
SIMPLECHECKBOX: I wasn't able to attach events nor get the value in any way last time I tested it (V1.31PTR) so it is kinda useless right now. Therefore I won't have an explanition here.
Edited: Replaced selfexecution with a less problematic approach
SIMPLECHECKBOX: I wasn't able to attach events nor get the value in any way last time I tested it (V1.31PTR) so it is kinda useless right now. Therefore I won't have an explanition here.
Edited: Replaced selfexecution with a less problematic approach
Other UI-Frame Tutorials
The following links might provide more insight into this subject.
UI: Change Lumber Text
[JASS/AI] - UI: Create a TextButton
[JASS/AI] - UI: Positionate Frames (important)
UI: toc-Files
UI: Reading a FDF
UI - The concept of Parent-Frames
[JASS/AI] - UI: FrameEvents and FrameTypes
UI: Frames and Tooltips
[JASS/AI] - UI: Creating a Bar
UI - Simpleframes
UI: What are BACKDROPs?
UI: GLUEBUTTON
UI: TEXTAREA the scrolling Text Frame
UI: EditBox - Text Input
[JASS/AI] - UI: Creating a Cam control
UI: Showing 3 Multiboards
UI: OriginFrames
Default Names for BlzGetFrameByName (Access to Existing game-Frames)
[JASS/AI] - UI: List - Default MainFrames (built in CreateAble)
UI: Change Lumber Text
[JASS/AI] - UI: Create a TextButton
[JASS/AI] - UI: Positionate Frames (important)
UI: toc-Files
UI: Reading a FDF
UI - The concept of Parent-Frames
[JASS/AI] - UI: FrameEvents and FrameTypes
UI: Frames and Tooltips
[JASS/AI] - UI: Creating a Bar
UI - Simpleframes
UI: What are BACKDROPs?
UI: GLUEBUTTON
UI: TEXTAREA the scrolling Text Frame
UI: EditBox - Text Input
[JASS/AI] - UI: Creating a Cam control
UI: Showing 3 Multiboards
UI: OriginFrames
Default Names for BlzGetFrameByName (Access to Existing game-Frames)
[JASS/AI] - UI: List - Default MainFrames (built in CreateAble)
Last edited:
