DialogControls-Buttons: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (page update)
m (disamb)
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{SideTOC}}
{{Wiki|disamb}}
== General ==
{{Informative|TokenNames common to most controls, such as x, y, w, h, text, idc... are not listed here.}}


Buttons are one way to add interactivity to your dialogs. Their corresponding ''type'' property is <tt>CT_BUTTON</tt>.
* [[CT_BUTTON]]
 
* [[CT_SHORTCUTBUTTON]]
Buttons can have different states (see screenshot) and will render slightly different to give the user a visual feedback on the button's state:
* [[CT_ACTIVETEXT]]
* '''Enabled''': the button has not been [[ctrlEnable|disabled]], it currently doesn't have any mouse or keyboard related focus
* '''Disabled''': the button has been explicitly disabled. It will not be clickable.
* '''Enabled''' + '''Focused''': As enabled; additionally it will have a small border of the color defined in the ''colorFocused'' property. This occurs when the button currently has focus (ie. is the default button or has been selected via the ''Tab'' key).
* '''Enabled''' + '''Active''': As enabled; additionally it will have a different background as specified in the ''colorBackgroundActive'' background. This occurs when the mouse is currently hovering over an unfocused button.
* '''Enabled''' + '''Active''' + '''Focused''': The combined result of the above two states. The mouse is currently hovering over the button in question and it has input focus.
 
Button can also have code attached to it in the ''action'' property. This code will be run when the button is clicked. Most often, you will have at least one button that closes the dialog via [[closeDialog]]. In this case you can provide ''0'' as the right-side parameter to close the currently open dialog.
 
=== Reserved IDCs ===
 
The engine reserves:
* IDC = 1 for (contextually) OK, or CONTINUE
* IDC = 2 for (contextually) CANCEL, ESCAPE, ABORT
 
{{Important|If you use these idc values, no action, no script, no event handler will operate on them.}}
 
 
== CT_BUTTON=1 ==
{| class="wikitable" width="100%" border="1" cellpadding="3" cellspacing="0" |
! bgcolor="#DDF" | Name
! bgcolor="#DDF" | Type
! bgcolor="#DDF" | Required
! bgcolor="#DDF" | Remark
! bgcolor="#DDF" | Script
|-
| '''type'''
| [[Integer]]
| Yes
| Control type: 1 (or CT_BUTTON, if using constants)
| {{n/a}}
|-
| '''style'''
| [[Integer]]
| Yes
| Display options:
* 0 (ST_LEFT): Text is left-aligned.
* 1 (ST_RIGHT) : Text is right-aligned.
* 2 (ST_CENTER): Text is centered.
| {{n/a}}
|-
| '''action'''
| [[String]]
| No
| Script command(s) to execute when button is pressed.<br>Must use double quotes; single quotes or curly brackets will ''not'' work.<br>
The variable "'''this'''" is available, and contains the unit that pressed the button, but unlike [[User_Interface_Event_Handlers|User Interface Event Handlers]] no "_this" information about the current control is passed.
| [[buttonSetAction]]
|-
|'''borderSize'''
| [[Number#Float|Float]]
| Yes
| If > 0 then a background (in the color defined in 'colorBorder') is drawn behind the button.
It extends to the left by the distance defined here, its height is slightly less than that of the button, and it is vertically centered.
The width extends to the right, to where the drop shadow starts. Stays static when button is pressed.
| {{n/a}}
|-
|'''colorBackground'''
| [[Color]]
| Yes
| Button's background color if not "active" (i.e. the mouse pointer is not over it).
| [[ctrlSetBackgroundColor]]
|-
|'''colorBackgroundActive'''
| [[Color]]
| Yes
| Background color if "active" (i.e. mouse pointer is over it).
| [[ctrlSetActiveColor]]
|-
|'''colorBackgroundDisabled'''||[[Color]]||Yes||Background color if control is disabled || {{n/a}}
|-
|'''colorBorder'''||[[Color]]||Yes||Color of left border, defined in 'borderSize' || {{n/a}}
|-
|'''colorDisabled'''||[[Color]]||Yes||Text color if control is disabled (via [[ctrlEnable]]) || {{n/a}}
|-
|'''colorFocused'''||[[Color]]||Yes||Alternating background color.
While the control has focus (but ''without'' the mouse pointer being over it) the background will cycle between 'colorFocused' and 'colorBackground'.
If both are the same, then the color will be steady.
| {{n/a}}
|-
|'''colorShadow'''||[[Color]]||Yes||Color of drop shadow behind button (not visible if button disabled) || {{n/a}}
|-
|'''colorText'''||[[Color]]||Yes||Color of text.||[[ctrlSetTextColor]]
|-
|'''default'''||[[Boolean]]||No||Whether the button will have focus upon loading the dialog.||[[ctrlSetFocus]]
|-
|'''offsetPressedX<br>offsetPressedY'''||[[Number#Float|Float]]||Yes||The button's text & background will move by this distance when pressed.
(If a shadow is defined, it will stay in place.)
| {{n/a}}
|-
|'''offsetX<br>offsetY'''||[[Number#Float|Float]]||Yes||Horizontal and vertical offset of drop shadow.
If 0, then shadow will be placed directly behind button
| {{n/a}}
|-
|'''url'''||[[String]]||No||URL which will be opened with default web browser. If tooltip is empty, URL will also be set as that. || {{n/a}}
|-
|'''soundClick'''||[[Array Sound|Sound]]||No||Sound to play when button is released after a click. || {{n/a}}
|-
|'''soundEnter'''||[[Array Sound|Sound]]||No||Sound to play when the mouse cursor is moved over the button. || {{n/a}}
|-
|'''soundEscape'''||[[Array Sound|Sound]]||No||Sound to play when the button was clicked via the mouse, and then released ''outside'' the button area. || {{n/a}}
|-
|'''soundPush'''||[[Array Sound|Sound]]||No||Sound to play when button is clicked. || {{n/a}}
|-
| '''text'''||[[String]]||No||Text to display. Will be vertically centered.||[[ctrlSetText]]
|-
| '''toolTip'''||[[String]]||No||Text that is shown in a little popup box when the mouse pointer is hovering over the button.||[[ctrlSetTooltip]]
|-
|}
 
=== Attributes class ===
 
{| class="wikitable" width="30%" border="1" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#DDF" | Name
! bgcolor="#DDF" | Type
! bgcolor="#DDF" | Remark
|-
| '''font'''
| string
|
|-
| '''shadow'''
| Integer
|
|-
| '''align'''
| String
| "center"
|-
| '''color'''
| Color Array
| "#000000"
|-
|-
|}<br clear="all">
 
* '''Example Config:'''
<syntaxhighlight lang="cpp">class RscButton
{
access = 0;
type = CT_BUTTON;
style = ST_LEFT;
x = 0; y = 0; w = 0.3; h = 0.1;
text = "";
font = "TahomaB";
sizeEx = 0.04;
colorText[] = {0,0,0,1};
colorDisabled[] = {0.3,0.3,0.3,1};
colorBackground[] = {0.6,0.6,0.6,1};
colorBackgroundDisabled[] = {0.6,0.6,0.6,1};
colorBackgroundActive[] = {1,0.5,0,1};
offsetX = 0.004;
offsetY = 0.004;
offsetPressedX = 0.002;
offsetPressedY = 0.002;
colorFocused[] = {0,0,0,1};
colorShadow[] = {0,0,0,1};
shadow = 0;
colorBorder[] = {0,0,0,1};
borderSize = 0.008;
soundEnter[] = {"",0.1,1};
soundPush[] = {"",0.1,1};
soundClick[] = {"",0.1,1};
soundEscape[] = {"",0.1,1};
};
class Dialog
{
class Controls
{
class OK: RscButton
{
idc=1;// fixed engine constant
x=y=w=y=whatever;
text="OK"
default=true;
};
class Cancel
{
idc=2; // fixed engine constant
x=y=somewhere else
default=false;
};
};
};</syntaxhighlight>
 
 
The following example uses almost the same code as the buttons shown in the example screenshot.
[[Image:Dialog controls button.jpg|thumb|110px|The same button four times in different states]]
 
* '''Example Config:'''
<syntaxhighlight lang="cpp">class MyButton
{
  idc = -1;
  type = CT_BUTTON;
  style = ST_LEFT;
  default = false;
  font = FontM;
  sizeEx = 0.03;
  colorText[] = { 0, 0, 0, 1 };
  colorFocused[] = { 1, 0, 0, 1 }; // border color for focused state
  colorDisabled[] = { 0, 0, 1, 0.7 }; // text color for disabled state
  colorBackground[] = { 1, 1, 1, 0.8 };
  colorBackgroundDisabled[] = { 1, 1, 1, 0.5 }; // background color for disabled state
  colorBackgroundActive[] = { 1, 1, 1, 1 }; // background color for active state
  offsetX = 0.003;
  offsetY = 0.003;
  offsetPressedX = 0.002;
  offsetPressedY = 0.002;
  colorShadow[] = { 0, 0, 0, 0.5 };
  colorBorder[] = { 0, 0, 0, 1 };
  borderSize = 0;
  soundEnter[] = { "", 0, 1 }; // no sound
  soundPush[] = { "buttonpushed.ogg", 0.1, 1 };
  soundClick[] = { "", 0, 1 }; // no sound
  soundEscape[] = { "", 0, 1 }; // no sound
  x = 0.4; y = 0.475;
  w = 0.2; h = 0.05;
  text = "Close";
  action = "closeDialog 0; hint ""Dialog closed. You are good to go now!""";
};</syntaxhighlight>
 
== CT_SHORTCUTBUTTON=16 ==
 
{|class="wikitable" width="100%" border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''action'''
| String
| Code executed when button is clicked.
|-
| '''Attributes'''
| Class
| see [[Dialog Control]] General
|-
| '''AttributesImage'''
| Class
| see [[Dialog Control]] General
|-
| '''animTextureNormal'''
| Texture
|
|-
| '''animTextureDisabled'''
| Texture
|
|-
| '''animTextureOver'''
| Texture
|
|-
| '''animTextureFocused'''
| Texture
|
|-
| '''animTexturePressed'''
| Texture
|
|-
| '''animTextureDefault'''
| Texture
|
|-
| '''textureNoShortcut'''
| Texture
| A custom Texture to be displayed alongside text. Position can be set in the ShortcutPos (Texture) and TextPos (text) class.
|-
| '''color'''
| Color Array
|
|-
| '''color2'''
| Color Array
|
|-
| '''colorActiveBackground'''
| Color Array
|
|-
| '''colorBackground'''
| Color Array
|
|-
| '''colorBackground2'''
| Color Array
|
|-
| '''colorDisabled'''
| Color Array
|
|-
| '''default'''
| Boolean
| If set to [[true]], this control is focused when the GUI is opened
|-
| '''HitZone'''
| Class
|
|-
| '''period'''
| Float
| Blinking period
|-
| '''periodFocus'''
| Float
| Blinking period when focused
|-
| '''periodOver'''
| Float
| Blinking period when mouse is hovering over the button
|-
| '''ShortcutPos'''
| Class
|
|-
| '''Shadow'''
| Integer
| 0,1 or 2
|-
| '''shortcuts'''
| array
| key short cuts. often over-ridden/ignored by engine
|-
| '''Size'''
| Float
| possibly a typo, used in conjunction with sizeEx
|-
| '''soundEnter'''
| Sound Array
|
|-
| '''soundPush'''
| Sound Array
|
|-
| '''soundClick'''
| Sound Array
|
|-
| '''soundEscape'''
| Sound Array
|
|-
| '''TextPos'''
| Class
|
|-
|}<br clear="all">
 
=== TextPos/HitZone ===
 
{| class="wikitable" width="30%" border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''Left'''
| Float
|
|-
| '''Top'''
| Float
|
|-
| '''Right'''
| Float
|
|-
| '''Bottom'''
| Float
|
|-
|}<br clear="all">
 
=== ShortcutPos ===
 
{| class="wikitable" width="30%" border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''Left'''
| Float
|
|-
| '''Top'''
| Float
|
|-
| '''w'''
| Float
| clearly an inconsistency with 'right'
|-
| '''h'''
| Float
| clearly an inconsistency with 'bottom'
|-
|}<br clear="all">
 
 
*'''Example Config:'''
<syntaxhighlight lang="cpp">class RscShortcutButton
{
  type = 16;
 
  class HitZone
  {
    left = 0.0;
    top = 0.0;
    right = 1.0;
    bottom = 1.0;
  };
  class ShortcutPos
  {
    left = 0.005;
    top = 0.005;
    w = 0.0225;
    h = 0.03;
  };
  class TextPos
  {
    left = 0.02;
    top = 0.005;
    right = 0.005;
    bottom = 0.005;
  };
  animTextureNormal = "#(argb,8,8,3)color(1,1,1,1)";
  animTextureDisabled = "#(argb,8,8,3)color(0.3,0.3,0.3,1)";
  animTextureOver = "#(argb,8,8,3)color(0.8,0.3,0,1)";
  animTextureFocused = "#(argb,8,8,3)color(1,0.5,0,1)";
  animTexturePressed = "#(argb,8,8,3)color(1,0,0,1)";
  animTextureDefault = "#(argb,8,8,3)color(0,1,0,1)";
  period = 0.1;
  periodFocus = 0.4;
  periodOver = 0.4;
  shortcuts[] = {};
  textureNoShortcut = "#(argb,8,8,3)color(0,0,0,0)";
  color[] = {0,0,0,0.6};
  color2[] = {0,0,0,1};
  colorDisabled[] = {0,0,0,0.3};
  colorBackground[] = {1,1,1,1};
  colorBackground2[] = {1,1,1,0.5};
  text = "";
  size = 0.04;
  class Attributes
  {
    font = "TahomaB";
    color = "#000000";
    align = "left";
    shadow = 0;
  };
};</syntaxhighlight>
 
== CT_ACTIVETEXT=11 ==
 
The active text control behaves very similar to buttons. It shows up as regular text with the additional functionality that you can click and select it. The dialog's currently selected Active Text control will be underlined to indicate it's status. By default, the first Active Text control is selected. When the mouse cursor hovers over an instance of this control, it will show up in the color defined in the ''colorActive'' property.
 
'''Notice:''' This control doesn't render the usually common ''colorBackground'' property and ''colorText'' is replaced with ''color''.
*For Arrowhead, this is not true. The properties are there, and it might be an attempt to standardise, or to account for pictures
{| class="wikitable" width="100%" border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''action'''
| String
| a statement that is executed when the control has been clicked
|-
| '''candrag'''
| Boolean
|
|-
| '''blinkingPeriod'''
| Float (Seconds)
| Makes the text start transparent, go to full opacity and back to full transparent in the amount of time specified.
|-
| '''color'''
| Color Array
| '''replaces ''colorText''''', standard text and underline color
|-
| '''colorActive'''
| Color Array
| text and underline color whenever the mouse hovers over the control
|-
| '''colorShade'''
| Color Array
|
|-
| '''colorFocused'''
| Color Array
|
|-
| '''colorDisabled'''
| Color Array
|
|-
| '''colorShade'''
| Color Array
|
|-
| '''colorText'''
| Color Array
|
|-
| <strike>'''colorBackground'''</strike>
| <strike>Color Array</strike>
| '''not applicable'''
|-
| '''colorBackground2'''
| Color Array
|
|-
| '''default'''
| Boolean
| Whether or not this control is the dialog's initially selected active text
|-
| '''pictureWidth/Height'''
| Float
|
|-
| '''sideDisabled'''
| argb
|
|-
| '''picture'''
| Texture
|
|-
| '''sideToggle'''
| argb
|
|-
| '''textHeight'''
| Float
|
|-
| '''soundEnter'''
| Sound Array
| the sound to play, when the cursor enters the button's bounds
|-
| '''soundDoubleClick'''
| Sound Array
| the sound to play, when the cursor enters the button's bounds
|-
| '''soundPush'''
| Sound Array
| the sound to play, when the button has been pushed
|-
| '''soundClick'''
| Sound Array
| the sound to play, when the button is being released
|-
| '''soundEscape'''
| Sound Array
| the sound to play, when the button has been pushed and the mouse button is released when not over the control.
|-
|}<br clear="all">
 
The following example uses almost the same code as the controls shown in the example screenshot.
[[Image:Dialog controls activetext.jpg|thumb|110px|Simple dialog with three Active Text controls]]
 
* '''Example Config:'''
<syntaxhighlight lang="cpp">class MyActiveText
{
  idc = -1;
  type = CT_ACTIVETEXT;
  style = ST_LEFT;
  x = 0.75; y = 0.5;
  w = 0.2; h = 0.035;
  font = FontM;
  sizeEx = 0.024;
  color[] = { 1, 1, 1, 1 };
  colorActive[] = { 1, 0.2, 0.2, 1 };
  soundEnter[] = { "", 0, 1 }; // no sound
  soundPush[] = { "", 0, 1 };
  soundClick[] = { "", 0, 1 };
  soundEscape[] = { "", 0, 1 };
  action = "hint ""Good choice!""";
  text = "Text";
  default = true;
};</syntaxhighlight>
 
[[Category: Dialogs]]

Latest revision as of 14:38, 7 February 2021

Disambiguation
This disambiguation page lists articles associated with the same title.
Retrieved from "https://community.bistudio.com/wiki?title=DialogControls-Buttons&oldid=244189"