Panel: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(Created page with "'''<code>vgui::Panel</code>''' is the base class of all VGUI elements. It is a rectangle which covers an area of the screen and can draw itself, handle events, and host child...")
 
(replace disambig note with Template:For)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''<code>vgui::Panel</code>''' is the base class of all [[VGUI]] elements. It is a rectangle which covers an area of the screen and can draw itself, handle events, and host children.
{{lang|Panel}}[[Category:Classes]][[Category:VGUI]]
{{toc-right}}
<span style="color:white; font-weight:bold"> {{For|about=the base VGUI element|the [[Portal 2]] puzzle element|[[Panels]]|}} </span>


== Important functions ==
<code>[[Panel|vgui::Panel]]</code> is the base class of all [[VGUI]] elements. It is a rectangle which covers an area of the screen and can draw itself, handle events, and host children.


== Functions ==
=== General ===
=== General ===
; <code>SetVisible([[bool]])</code>
; <code>[[bool]] IsVisible()</code>
; <code>[[bool]] IsFullyVisible()</code>
: Invisible panels and their children are not drawn or updated and do not receive input messages. <code>IsFullyVisible()</code> checks parent panels for visibility too.
; <code>SetEnabled([[bool]])</code>
; <code>IsEnabled()</code>
: Disabled panels do not receive input and are often drawn with muted colours to indicate this.
; <code>OnThink()</code>
: Called every frame before painting if the panel is visible. {{todo|What about <code>Think()</code>? Is it obsolete? Does it run even if the panel isn't visible?}}
; <code>void OnTick()</code>
: Called at regular intervals if <code>[[IVGui|ivgui()]]->AddTickSignal()</code> is called.


; <code>SetVisible([[bool]])</code>
=== Layout ===
: Whether the panel is drawn. {{todo|Does processing continue?}}
; <code>[[bool]] IsProportional()</code>
; <code>SetProportional([[bool]])</code>
: {{confirm|When a panel is proportional, its layout values are interpreted as being relative to a 640*480 screen. This allows you to position a panel at 64,48 and be certain that it will always be 10% away from the screen edge, regardless of the current resolution. This system does not respond well to changes in aspect ratio. The <code>c</code> and <code>r</code> [[#Script parameters|.res keywords]] were added to resolve this issue.}}
; <code>SetPos(), GetPos(), SetSize(), GetSize(), SetBounds(), GetBounds(), GetWide(), SetWide(), GetTall(), SetTall()</code>
: Functions for configuring the panel's position or size, or both at once.


=== Painting ===
=== Painting ===
 
A panel is drawn by its "paint" functions. <code>PaintBackground()</code> and <code>Paint()</code> are enabled by default.
A panel is drawn in its "paint" functions. <code>PaintBackground()</code> and <code>Paint()</code> are enabled by default.


; <code>PaintBackground()</code>
; <code>PaintBackground()</code>
Line 27: Line 44:
; <code>PostChildPaint()</code>
; <code>PostChildPaint()</code>
; <code>SetPostChildPaintEnabled([[bool]])</code>
; <code>SetPostChildPaintEnabled([[bool]])</code>
: Performs arbitrary drawing after the panel's children have been painted (i.e. on top of them).
: Performs arbitrary drawing after the panel's children have been painted (i.e. above them).
; <code>SetSkipChildDuringPainting(Panel *child)</code>
: Prevents a child from drawing, {{confirm|without stopping it from thinking}}.
; <code>SetAlpha([[int]])</code>
: Sets the [[alpha]] of this panel and its children panels. 0 is invisible, 255 is opaque.
 
=== Hierarchy ===
Each panel has one parent and can have many children. Unless made a popup, children are drawn relative to and within the confines of their parent panel.
 
==== Parents ====
; <code>Panel *GetParent()</code>
; <code>[[VPANEL]] GetVParent()</code>
; <code>SetParent(Panel*)</code> ''or'' <code>SetParent([[VPANEL]])</code>
: Gets/sets this panel's parent.
; <code>[[bool]] HasParent([[VPANEL]])</code>
: Is the given panel somewhere above this one in the hierarchy?
 
==== Children ====
; <code>[[int]] GetChildCount()</code>
; <code>[[Panel]] *GetChild([[int]] index)</code>
; <code>[[Panel]] *FindChildByName([[string|char*]] childName, [[bool]] recurseDown = false)</code>
: Provides access to child panels.
; <code>OnChildAdded([[VPANEL]] child)</code>
: Called when a child is added to this panel.
 
==== Popups ====
; <code>PopupMakePopup([[bool]] showTaskbarIcon = true,[[bool]] disabled = false)</code>
; <code>bool IsPopup()</code>
: Popup panels draw outside of their parent's space and do not follow it around.
 
== Script Parameters ==
These can be used within a <code>.res</code> layout file.
 
{{ScriptVar|fieldName|string|Sets the control's name. Default is NULL.}}
{{ScriptVar|wide|int}}
{{ScriptVar|tall|int|The initial size of the panel.}}
{{ScriptVar|xpos|int}}
{{ScriptVar|ypos|int|The X and Y position of the panel's pinned corner relative to its parent. By default this value is an offset from the left/top edge, but the special characters <code>c</code> and <code>r</code> allow positioning relative to the centre and right/bottom edge respectively. Examples:
:* <code>xpos 300</code>
:* <code>xpos r300</code>
:* <code>xpos c0</code>
}}
{{ScriptVar|PinCorner|choices|The pinned corner is the one positioned at xpos/ypos. Values are:
:* <code>TOPLEFT</code> (default)
:* <code>TOPRIGHT</code>
:* <code>BOTTOMLEFT</code>
:* <code>BOTTOMRIGHT</code>
}}
{{ScriptVar|PinnedCornerOffsetX|int}}
{{ScriptVar|PinnedCornerOffsetY|int}}
{{ScriptVar|UnpinnedCornerOffsetX|int}}
{{ScriptVar|UnpinnedCornerOffsetY|int|{{todo}}}}
{{ScriptVar|zpos|int|The Z position. Default is <code>1</code>. Higher numbers are drawn on top of lower numbers.}}
{{ScriptVar|IgnoreScheme|bool|{{todo|"Only get colors if we're ignoring the scheme."}} See also <code>[[IScheme]]</code>.}}
{{ScriptVar|visible|bool|Whether the control is visible.}}
{{ScriptVar|enabled|bool|Whether the control can be used.}}
{{ScriptVar|tabPosition|int|Controls the order in which panels are focused on when {{key|tab}} is pressed. Valid range is 0-255. Default is 0.}}
{{ScriptVar|tooltiptext|string|Text displayed when mouse is hovered over this panel. No support on consoles.}}
{{ScriptVar|paintbackground|bool}}
{{ScriptVar|paintborder|bool|Whether to draw the background/border of the panel. Default is -1, which means no value will be applied.}}
{{ScriptVar|AutoResize|choices|Sets which edges of the panel can be resized. Values are:
:* <code>NO</code> (default)
:* <code>RIGHT</code>
:* <code>DOWN</code>
:* <code>DOWNANDRIGHT</code>
}}

Latest revision as of 00:18, 30 June 2025

English (en)中文 (zh)Translate (Translate)
This article is about the base VGUI element. For the Portal 2 puzzle element, see Panels.

vgui::Panel is the base class of all VGUI elements. It is a rectangle which covers an area of the screen and can draw itself, handle events, and host children.

Functions

General

SetVisible(bool)
bool IsVisible()
bool IsFullyVisible()
Invisible panels and their children are not drawn or updated and do not receive input messages. IsFullyVisible() checks parent panels for visibility too.
SetEnabled(bool)
IsEnabled()
Disabled panels do not receive input and are often drawn with muted colours to indicate this.
OnThink()
Called every frame before painting if the panel is visible.
Todo: What about Think()? Is it obsolete? Does it run even if the panel isn't visible?
void OnTick()
Called at regular intervals if ivgui()->AddTickSignal() is called.

Layout

bool IsProportional()
SetProportional(bool)
Confirm:When a panel is proportional, its layout values are interpreted as being relative to a 640*480 screen. This allows you to position a panel at 64,48 and be certain that it will always be 10% away from the screen edge, regardless of the current resolution. This system does not respond well to changes in aspect ratio. The c and r .res keywords were added to resolve this issue.
SetPos(), GetPos(), SetSize(), GetSize(), SetBounds(), GetBounds(), GetWide(), SetWide(), GetTall(), SetTall()
Functions for configuring the panel's position or size, or both at once.

Painting

A panel is drawn by its "paint" functions. PaintBackground() and Paint() are enabled by default.

PaintBackground()
SetPaintBackgroundEnabled(bool)
Draws the background of the panel.
Paint()
SetPaintEnabled(bool)
Draws the contents of the panel.
Confirm:Does not draw children.
PaintBorder()
SetPaintBorderEnabled(bool)
SetBorder(IBorder *border)
IBorder *GetBorder()
Paints a border around the panel. SetBorder() must be called before SetPaintBorderEnabled().
  • Get an IBorder from IScheme::GetBorder() in ApplySchemeSettings().
  • See swarm/resource/sourcescheme.res for examples of border definitions.
PostChildPaint()
SetPostChildPaintEnabled(bool)
Performs arbitrary drawing after the panel's children have been painted (i.e. above them).
SetSkipChildDuringPainting(Panel *child)
Prevents a child from drawing,
Confirm:without stopping it from thinking
.
SetAlpha(int)
Sets the alpha of this panel and its children panels. 0 is invisible, 255 is opaque.

Hierarchy

Each panel has one parent and can have many children. Unless made a popup, children are drawn relative to and within the confines of their parent panel.

Parents

Panel *GetParent()
VPANEL GetVParent()
SetParent(Panel*) or SetParent(VPANEL)
Gets/sets this panel's parent.
bool HasParent(VPANEL)
Is the given panel somewhere above this one in the hierarchy?

Children

int GetChildCount()
Panel *GetChild(int index)
Panel *FindChildByName(char* childName, bool recurseDown = false)
Provides access to child panels.
OnChildAdded(VPANEL child)
Called when a child is added to this panel.

Popups

PopupMakePopup(bool showTaskbarIcon = true,bool disabled = false)
bool IsPopup()
Popup panels draw outside of their parent's space and do not follow it around.

Script Parameters

These can be used within a .res layout file.

fieldName  <string>
Sets the control's name. Default is NULL.
wide  <integer>
tall  <integer>
The initial size of the panel.
xpos  <integer>
ypos  <integer>
The X and Y position of the panel's pinned corner relative to its parent. By default this value is an offset from the left/top edge, but the special characters c and r allow positioning relative to the centre and right/bottom edge respectively. Examples:
  • xpos 300
  • xpos r300
  • xpos c0
PinCorner  <choices>
The pinned corner is the one positioned at xpos/ypos. Values are:
  • TOPLEFT (default)
  • TOPRIGHT
  • BOTTOMLEFT
  • BOTTOMRIGHT
PinnedCornerOffsetX  <integer>
PinnedCornerOffsetY  <integer>
UnpinnedCornerOffsetX  <integer>
UnpinnedCornerOffsetY  <integer>
[Todo]
zpos  <integer>
The Z position. Default is 1. Higher numbers are drawn on top of lower numbers.
IgnoreScheme  <boolean>
Todo: "Only get colors if we're ignoring the scheme."
See also IScheme.
visible  <boolean>
Whether the control is visible.
enabled  <boolean>
Whether the control can be used.
tabPosition  <integer>
Controls the order in which panels are focused on when Tab ⇆ is pressed. Valid range is 0-255. Default is 0.
tooltiptext  <string>
Text displayed when mouse is hovered over this panel. No support on consoles.
paintbackground  <boolean>
paintborder  <boolean>
Whether to draw the background/border of the panel. Default is -1, which means no value will be applied.
AutoResize  <choices>
Sets which edges of the panel can be resized. Values are:
  • NO (default)
  • RIGHT
  • DOWN
  • DOWNANDRIGHT
Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Panel&oldid=484426"