UI: Frames and Tooltips

Introduction

In the UI-frame natives, tooltips are frames that are on default hidden. When one hovers the frame the tooltip is assigned to, the tooltip becomes visible. Tooltips itself are also frames that can have childs and be customized.

That is the native one uses to make a tooltip-Frame become some frames tooltip.

BlzFrameSetTooltip takes framehandle frame, framehandle tooltip returns nothing

SimpleFrames and Tooltips

SimpleFrames can normally not have tooltips and they can also not be a tooltip for Frames. A SIMPLEBUTTON can have other SimpleFrames as tooltip.

One can give a SimpleFrame a tooltip by creating a substitute FRAME which copies all points of the simpleframe. That substitute only handles the tooltip and is empty. When one hovers the SimpleFrame the substitute FRAME kicks in and shows its tooltip giving the feeling that it is the SimpleFrames tooltip. That way also SimpleFrames or BACKDROPs can have tooltips.

Example 1

In example 1, we create 3 Frames: a BACKDROP, a TEXT and a FRAME. The BACKDROP shows a Paladin icon. The FRAME copies the points of the BACKDROP and handles the Tooltip showing. As last the TEXT-Frame is the tooltip itself which is shown when one hovers the Paladin icon with the mouse.
The FRAME is needed in this example because BACKDROPs can not have events nor tooltips. FRAME can't have events either but can have a tooltip.

In this example all frames are created with BlzCreateFrameByType, that is done so one does not have to bother fdf for this example.

BlzCreateFrameByType takes string typeName, string name, framehandle owner, string inherits, integer createContext

Code (Lua):

function Face()
  local face = BlzCreateFrameByType("BACKDROP", "Face", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), "", 0)--Create a new frame of Type BACKDROP
   local faceHover = BlzCreateFrameByType("FRAME", "FaceFrame", face,"", 0) --face is a BACKDROP it can not have events nor a tooltip, thats why one creates an empty frame managing that.
   local tooltip = BlzCreateFrameByType("TEXT", "FaceFrameTooltip", face,"", 0)--Create a new frame of Type TEXT
   --faceHover would be unneeded if face would support events/tooltip

   BlzFrameSetAllPoints(faceHover, face) --faceHover copies the size and position of face.
   BlzFrameSetTooltip(faceHover, tooltip) --when faceHover is hovered with the mouse frame tooltip becomes visible.

   BlzFrameSetSize(face, 0.04, 0.04)
   BlzFrameSetAbsPoint(face, FRAMEPOINT_CENTER, 0.4, 0.3)
   BlzFrameSetAbsPoint(tooltip, FRAMEPOINT_CENTER, 0.2, 0.3)
   BlzFrameSetText(tooltip, "Human Paladin Face")

   BlzFrameSetTexture(face, "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin",0, true)--face uses paladin blp as texture.
end
 

That code has to be executed. It does not run by itself.

• Start
  • Events
    • Map initialization
  • Conditions
  • Actions
    • Custom script: Face()

Example 2

The tooltip in the previous example is not really good looking, it's just some Text on the screen. I want it to be in a box and look similar to the default tooltip. Well because such a frame does not exist in the default fdf and one can not manipulate the shown text of the default tooltip frame (as far as I know), one has to create it.

That will be our Boxed Text fdf. "BoxedText" is the frame we create. What can that "BoxedText" do? It mimics the default Tooltip-Box and has 2 children: "BoxedTextTitle" and "BoxedTextValue". The title is shown in the first line and below that title BoxedTextValue will be placed. BoxedTextValue has a smaller Text size than BoxedTextTitle.

Code (Text):

// -- LOCAL TEMPLATES -------------------------------------------------------
Frame "BACKDROP" "BoxedTextBackgroundTemplate" {
        DecorateFileNames, //Look-Up Names in some String table (for example gameinterface)
        BackdropTileBackground, //Tile mode enabled
        BackdropBackground  "ToolTipBackground", //BackgroundFile
        BackdropCornerFlags "UL|UR|BL|BR|T|L|B|R",
        BackdropCornerSize  0.008, //higher numbers make the corners bigger.
        BackdropBackgroundInsets 0.0022 0.0022 0.0022 0.0022, //makes the background smaller, from the outside.
        BackdropEdgeFile  "ToolTipBorder", //the border File
        BackdropBlendAll,
}
// -- Frames -------------------------------------------------------
Frame "BACKDROP" "BoxedText" INHERITS "BoxedTextBackgroundTemplate" {
   UseActiveContext,
 
   Frame "TEXT" "BoxedTextTitle" {
       UseActiveContext,
       DecorateFileNames,
       SetPoint TOPLEFT, "BoxedText", TOPLEFT, 0.005, -0.005, //Positionate "BoxedTextSimpleTitle"'s TOPLEFT to "BoxedText"'s TOPLEFT with an offset
       SetPoint TOPRIGHT, "BoxedText", TOPRIGHT, -0.005, -0.005,
       FontFlags "FIXEDSIZE",
       FrameFont "MasterFont", 0.014, "",
       FontColor 1.0 1.0 1.0 1.0, //Red Green Blue Alpha 0.0 to 1.0
       FontShadowColor 0.0 0.0 0.0 0.9,
       FontShadowOffset 0.001 -0.001,
   }
 
   Frame "TEXT" "BoxedTextValue" {
       UseActiveContext,
       DecorateFileNames,
       SetPoint TOPLEFT, "BoxedText", TOPLEFT, 0.005, -0.02,
       SetPoint BOTTOMRIGHT,  "BoxedText", BOTTOMRIGHT, -0.005, 0.005,
       FontFlags "FIXEDSIZE",
       FrameFont "MasterFont", 0.012, "",
       FontColor 1.0 1.0 1.0 1.0,
       FontShadowColor 0.0 0.0 0.0 0.9,
       FontShadowOffset 0.001 -0.001,
   }
}
 

Now we need to change the code a bit. Instead of TEXT, we now create a Frame of name "BoxedText". Also the tooltip is not a TEXT anymore, it's now a box, means we have to access the children of the box showing the text. They are BoxedTextValue and BoxedTextTitle.

Code (Lua):

function Face2()
   BlzLoadTOCFile("war3mapimported\\BoxedText.toc")
  local face = BlzCreateFrameByType("BACKDROP", "Face", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), "", 0)--Create a new frame of Type BACKDROP
   local faceHover = BlzCreateFrameByType("FRAME", "FaceFrame", face,"", 0) --face is a BACKDROP it can not have events nor a tooltip, thats why one creates an empty frame managing that.
   local tooltip = BlzCreateFrame("BoxedText", face, 0, 0)--Create the BoxedText Frame
   --faceHover would be unneeded if face would support events/tooltip

   BlzFrameSetAllPoints(faceHover, face) --faceHover copies the size and position of face.
   BlzFrameSetTooltip(faceHover, tooltip) --when faceHover is hovered with the mouse frame tooltip becomes visible.

   BlzFrameSetSize(face, 0.04, 0.04)
   BlzFrameSetAbsPoint(face, FRAMEPOINT_CENTER, 0.4, 0.3)
   BlzFrameSetAbsPoint(tooltip, FRAMEPOINT_CENTER, 0.2, 0.3)
   BlzFrameSetSize(tooltip, 0.15, 0.08)

  BlzFrameSetText(BlzGetFrameByName("BoxedTextValue",0), "Human Paladin Face, but it is not uther.")--BoxedText has a child showing the text, set that childs Text.
    BlzFrameSetText(BlzGetFrameByName("BoxedTextTitle",0), "Paladin")--BoxedText has a child showing the Title-text, set that childs Text.

   BlzFrameSetTexture(face, "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin",0, true)--face uses paladin blp as texture.
end
 

That code does not execute itself, one has to execute it.

• Start
  • Events
    • Map initialization
  • Conditions
  • Actions
    • Custom script: Face2()

That is nice, Text in a box, also similar to the default one.

Instead of creating such a BoxedText one could use a TEXTAREA. TEXTAREA does most of BoxedText, but it has a scrollbar blocking a part of the right side and it requires the box to have a min size (else it crashes the game / the thread). Also it becomes a bit tricky with the title.

ChangeLog: Added <UseActiveContext,> to the children in fdf. Without it, the tooltip text inside the box would work wrong for createcontext not be 0.

---

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)

 

Thanks for your tutorial, could you mabye make a JASS example? Can't convert my map to lua

 

I've already tried it:

Code (Text):

function face2 takes nothing returns nothing
    call LoadToc("war3mapimported\\BoxedText.toc")
    local framehandle face = BlzCreateFrameByType("BACKDROP", "Face", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), "", 0)
    local framehandle faceHover = BlzCreateFrameByType("FRAME", "FaceFrame", face,"", 0)
    local framehandle tooltip = BlzCreateFrame("BoxedText", face, 0, 0)
 
    call BlzFrameSetAllPoints(faceHover, face)
    call BlzFrameSetTooltip(faceHover, tooltip)
 
    call BlzFrameSetSize(face, 0.04, 0.04)
    call BlzFrameSetAbsPoint(face, FRAMEPOINT_CENTER, 0.4, 0.3)
    call BlzFrameSetAbsPoint(tooltip, FRAMEPOINT_CENTER, 0.2, 0.3)
    call BlzFrameSetPoint(tooltip, FRAMEPOINT_BOTTOM, face, FRAMEPOINT_TOP, 0.0, 0.0)
    call BlzFrameSetSize(tooltip, 0.15, 0.08)
 
    call BlzFrameSetText(BlzGetFrameByName("BoxedTextValue", 0), "Human Paladin Face, but it is not uther.")
    call BlzFrameSetText(BlzGetFrameByName("BoxedTextTitle", 0), "Paladin")
 
    call BlzFrameSetTexture(face, "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin",0, true)
endfunction

But the JASS-Compiler throws an error relatively early:

 

in jass local variables have to be created as 1.actions of a function. LoadToc is no local and is done before locals are created, making the locals the 2.Actions which is not allowed.
Do the toc loading in an seperate funtion which executes before that one runs. Or use the vanila one BlzLoadTOCFile and save that in a local boolean.

 

@Coldgamer no fear xorkatoss is near!

Spoiler: Code

Code (vJASS):

function CreateUther takes nothing returns nothing
    local framehandle face = BlzCreateFrameByType("BACKDROP", "Face", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), "", 0)
    local framehandle faceHover = BlzCreateFrameByType("FRAME", "FaceFrame", face,"", 0)
    local framehandle tooltip = BlzCreateFrame("BoxedText", face, 0, 0)
    call BlzFrameSetAllPoints(faceHover, face)
    call BlzFrameSetTooltip(faceHover, tooltip)
 
    call BlzFrameSetSize(face, 0.04, 0.04)
    call BlzFrameSetAbsPoint(face, FRAMEPOINT_CENTER, 0.4, 0.3)
//  call BlzFrameSetAbsPoint(tooltip, FRAMEPOINT_CENTER, 0.2, 0.3)
    call BlzFrameSetPoint(tooltip, FRAMEPOINT_BOTTOM, face, FRAMEPOINT_TOP, 0.0, 0.0)
    call BlzFrameSetSize(tooltip, 0.15, 0.08)
    call BlzFrameSetText(BlzGetFrameByName("BoxedTextValue", 0), "Human Paladin Face, but it is not uther.")
    call BlzFrameSetText(BlzGetFrameByName("BoxedTextTitle", 0), "Paladin")
 
    call BlzFrameSetTexture(face, "ReplaceableTextures\\CommandButtons\\BTNHeroPaladin",0, true)
endfunction
//===========================================================================
function InitTrig_Uther takes nothing returns nothing
   set gg_trg_Uther = CreateTrigger(  )
   call TriggerRegisterTimerEventSingle( gg_trg_Uther, 1.00 )
   call TriggerAddAction( gg_trg_Uther, function CreateUther)
   call BlzLoadTOCFile("war3mapimported\\BoxedText.toc")
endfunction

Who would have though jass was so easy?

I had to convert this for me because lua is so inconvenient, having all your code in the map header is a HUGE mess, I mean who even though creating lua was gonna be useful? am I right? lol

anyway so I thought why not share it here to help some people, enjoy.

 

Still a bit confused on how to make use of this one.

I want 20 different frames of "BoxedText" for my Inventory System but how would I go about doing so? If I use BlzFrameSetText(BlzGetFrameByName("BoxedTextValue",0) how do I reference a specific frame?

Sorry if this is unclear or a stupid question. Anyway, here's an idea of what I'm trying to make work, I cropped out the Button creation and other stuff so hopefully it will still make sense:

Code (Lua):

function CreateTooltip(player)
    --[tooltipframe] is a unique Integer that I change each time I run CreateTooltip(). So each frame will have it's own unique index.
    InventorySlots[player][tooltipframe] = BlzCreateFrame("BoxedText", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 1, 0)
    BlzFrameSetAbsPoint(InventorySlots[player][tooltipframe], FRAMEPOINT_CENTER, 0.4, 0.3)
    BlzFrameSetSize(InventorySlots[player][tooltipframe], 0.15, 0.12)
    BlzFrameSetVisible(InventorySlots[player][tooltipframe], false)
    MouseEnter(player)
end
 

Code (Lua):

function MouseEnter(player)
    local trigger = CreateTrigger()
    BlzTriggerRegisterFrameEvent(trigger, InventorySlots[player][buttonframe], FRAMEEVENT_MOUSE_ENTER)
    TriggerAddAction(trigger, function()
        BlzFrameSetVisible(InventorySlots[player][tooltipframe], true)
        BlzFrameSetText(BlzGetFrameByName("BoxedTextValue",0), InventorySlots[player][itemdescription])
        --InventorySlots[player][itemdescription] will be a unique String associated with this specific Inventory Slot
    end)
end
 

With this setup, only the last created Tooltipframe will display any text. So how do I reference specific Frames using: BlzFrameSetText(BlzGetFrameByName("BoxedTextValue",0), "some string"

I had this working before using:

Code (Lua):

--Instead of "BoxedText" Frame I used:
InventorySlots[player][tooltipframe] = BlzCreateFrame("EscMenuTextAreaTemplate", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 1, 0)

--Instead of GetFrameByName I used:
BlzFrameSetText(InventorySlots[player][tooltipframe], InventorySlots[player][itemdescription])
 

 

This BoxedText Frame has 2 TEXT child-Frames: "BoxedTextTitle" and "BoxedTextValue". When creating "BoxedText" the child Frames are also created and get the same createcontext number, that is the last argument in the create function. Each of the now created Frames takes a Slot in an inner storage. When using BlzGetFrameByName one reads that inner storage and gets the Frame saved with that Name at that index/createcontext. In case one wants to Access Frames with BlzGetFrameByName one has to avoid losing Frames hence unique names/createcontexts.
But that is not nessacary when saving all later edited Frames in variables. After creating the mainframe "BoxedText", you use BlzGetFrameByName and also save the child Frames in variables then you can access them later using the variables, without having to care about createcontext or framenames.

Code (Lua):

--Create the mainframe "BoxedText"
local tooltip = BlzCreateFrame("BoxedText", parent, 0, 0)
--Get the childFrames and save them in variables
local tooltipValue = BlzGetFrameByName("BoxedTextValue",0)
local tooltipTitle = BlzGetFrameByName("BoxedTextTitle",0)
--Set the text of the childFrames
BlzFrameSetText(tooltipValue, "Super Long Text")
BlzFrameSetText(tooltipTitle, "Title")
 

That is cause a TEXTAREA is all in one BACKDROP, SCROLLBAR and TEXT.
One can also set the text of a child Frame if the child is setuped as for example as ButtonText in the fdf as seen in "ScriptDialogButton".​

 

Excellent, I got it working. Much appreciated!

 

Great tutorial, as always!

Anyway, I now have two questions:

First - The tooltip apparently makes a button un-clickable. Do you know a workaround for this? Is there a way to make the frames "transparent" so it would recognize mouseover and clicking through the different frames?

Second - Is it possible to make the background on the tooltip itself a bit more transparent? I moved it to the right corner above the command card and replicated the size and everything of the default tooltip, so now it kinda sticks out, that the background is not as transparent. I checked out fdf file, but there's nothing about the background's color.

 

When having a button you can skip the hoverFrame then the button has the Tooltip directly. The text frames of the tooltip fight for mouse control, if you disable them with

BlzFrameSetEnable(frame, false)

then they won't anymore. One can also disable the mouse control for an frame in fdf by adding

LayerStyle "IGNORETRACKEVENTS",

to the frames capable of mouse events

There is

BlzFrameSetAlpha(frame, 0 to 255)

codewise to make a frame less visible. It will affect child-Frames as well.

 

Right, of course! Thanks a lot for the help again!

 

I was wondering if there is a way to (semi) automatically resize a frame based on the amount of text in it.

I am currently using a frame definition that is very similar to your example in this tutorial:

Code (Lua):

Frame "BACKDROP" "Tooltip" {
    DecorateFileNames,
        BackdropTileBackground,
    BackdropBackground "ToolTipBackground",
        BackdropCornerFlags "UL|UR|BL|BR|T|L|B|R",
        BackdropCornerSize 0.008,
        BackdropBackgroundInsets 0.0022 0.0022 0.0022 0.0022,
        BackdropEdgeFile "ToolTipBorder",
        BackdropBlendAll,
    UseActiveContext,
    Frame "TEXT" "TooltipTitle" {
        UseActiveContext,
        DecorateFileNames,
        SetPoint TOPLEFT, "Tooltip", TOPLEFT, 0.0043, -0.005,
        SetPoint TOPRIGHT, "Tooltip", TOPRIGHT, -0.0043, -0.005,
        FontFlags "FIXEDSIZE",
        FrameFont "MasterFont", 0.011, "",
        FontColor 1.0 1.0 1.0 1.0,
        FontShadowColor 0.0 0.0 0.0 0.9,
        FontShadowOffset 0.001 -0.001,
    }
    Frame "TEXT" "TooltipText" {
        UseActiveContext,
        DecorateFileNames,
        SetPoint TOPLEFT, "Tooltip", TOPLEFT, 0.0043, -0.0275,
        SetPoint BOTTOMRIGHT,  "Tooltip", BOTTOMRIGHT, -0.0043, -0.0275,
        FontFlags "FIXEDSIZE",
        FrameFont "MasterFont", 0.011, "",
        FontColor 1.0 1.0 1.0 1.0,
        FontShadowColor 0.0 0.0 0.0 0.9,
        FontShadowOffset 0.001 -0.001,
    }
}

Then I run the following code to create the frame, give it a size and position, and add text;

Code (Lua):

local f = BlzCreateFrame("Tooltip", f, 0, 0)
BlzFrameSetAbsPoint(f, FRAMEPOINT_BOTTOMRIGHT, 0.7992, 0.063)
BlzFrameSetSize(f, 0.2884, 0.109)
local f2 = BlzGetFrameByName("TooltipText", 0)
BlzFrameSetText(f2, BlzGetAbilityResearchExtendedTooltip(skill, 0))

In this example I aim to make a tooltip with variable text, containing Skill information.
After creation, I can see that the text that is displayed in "TooltipText" respects the width that I have set for the highest level frame "Tooltip".

However, if there is a lot of text, it might overflow the backdrop frame.
Perhaps there is a keyword that automatically updates the size of the actual text frame, which I can then use to resize the backdrop?

Otherwise I would have to make a function that counts characters and linebreaks and then adjusts the frame size accordingly.

 

One can have a variable Height by using 0 inside BlzFrameSetSize(frame, x, 0) (or not mentioning it in fdf) then it is autocalced, but you still need a vaild Width.
With no Height it scales to the bottom/Top, depends which point you placed the Text-Frame with.
If the Text manges the size one has to revert the relative position. Then the text is abs posed but the backdrop's position depends on the text.

Code (Lua):

do
    local real = MarkGameStarted
 function MarkGameStarted()
        real()
    local backDrop = BlzCreateFrame("QuestButtonBaseTemplate", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 0, 0)
    local text = BlzCreateFrameByType("TEXT", "TestText", backDrop, "", 0)
    BlzFrameSetAbsPoint(text, FRAMEPOINT_TOPRIGHT, 0.8, 0.55)
    BlzFrameSetSize(text, 0.35, 0)

    BlzFrameSetPoint(backDrop, FRAMEPOINT_TOPLEFT, text, FRAMEPOINT_TOPLEFT, -0.01, 0.01)
    BlzFrameSetPoint(backDrop, FRAMEPOINT_BOTTOMRIGHT, text, FRAMEPOINT_BOTTOMRIGHT, 0.005, -0.01)
    BlzFrameSetText(text, BlzGetAbilityExtendedTooltip(FourCC("AHfs"), 0))

    backDrop = BlzCreateFrame("QuestButtonBaseTemplate", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 0, 0)
    text = BlzCreateFrameByType("TEXT", "TestText", backDrop, "", 0)
    BlzFrameSetAbsPoint(text, FRAMEPOINT_TOPRIGHT, 0.42, 0.55)
    BlzFrameSetSize(text, 0.2, 0)

    BlzFrameSetPoint(backDrop, FRAMEPOINT_TOPLEFT, text, FRAMEPOINT_TOPLEFT, -0.01, 0.01)
    BlzFrameSetPoint(backDrop, FRAMEPOINT_BOTTOMRIGHT, text, FRAMEPOINT_BOTTOMRIGHT, 0.01, -0.01)
    BlzFrameSetText(text, BlzGetAbilityTooltip(FourCC("AHfs"), 0))
 end
end

Edited: Replaced selfexecution with a less problematic approach

 

Thanks, works great!

 

Seems to be bugged when you create a custom buttom in the command grid, the tooltip won't show up. To check if my code is wrong i moved the button around a bit and as soon as it was out of the command grid the tooltip showed up again when the mouse is hovered over my button.


Below a link to the screenshot I made to illustrate what I mean. My custom button resides next to "Patrol" and the tooltip is not working there.
https://cdn.discordapp.com/attachments/311662737015046144/765804950566731776/unknown.png

 

The mouseinteraction prioritizes SimpleFrames. There is a SimpleFrame behind the commandbar which controls the mouse .
Even though it looks like the button is above, for the mouse interaction it is not.

Mouse interaction in one group of Frames (Simple)Frame is rule by Level/Parentship

 

Setting a Frame as Tooltip can break it's capability to leave the 4:3 Screen. It is suggested to avoid such a case by adding an empty Parent FRAME for the tooltip which becomes internal the Tooltip for the game.

Using BlzFrameSetTooltip twice with the same frame pair, crashes the game when the Frame is hovered.
BlzFrameSetTooltip(frame, tooltip)
BlzFrameSetTooltip(frame, tooltip)