Button

From Multiverse

Jump to: navigation, search
User Interface Widgets

Browser
Button
CheckButton
EditBox
FontString
Frame
LayeredRegion

Region
Script
ScrollFrame
ScrollingMes-   sageFrame
Slider
StatusBar
Texture

A Button is a rectangular area that displays text and an image. The user can click on the button to initiate events. When the button is enabled, clicking on it calls the Click() method; when it's disabled, clicking on it has no effect.

Derived from: Frame.

Contents

[edit]

Tag 

<Button
text=buttonText
alpha=number
enableKeyboard=[true|false] 
enableMouse=[true|false]
frameStrata=[TOOLTIP | FULLSCREEN_DIALOG | FULLSCREEN | DIALOG | HIGH | MEDIUM | LOW | BACKGROUND]
id=number
parent=widgetName
hidden=[true|false]
inherits=parentWidgetName
name=widgetName
setAllPoints=[true|false]
virtual=[true|false]
>
...
</Button>
[edit]

Attributes

Button has the following special attribute:

  • text - initial text to display in the button; change with SetText().


Button inherits these attributes from Frame:

  • alpha - Opacity of the frame widget; 0 is transparent, 1 opaque.
  • enableKeyboard - one of true or false. If this is set to true, keyboard events will be intercepted by this frame, and will not be passed through, even if they are not handled by a script handler such as OnKeyDown.
  • enableMouse - one of true or false. If this is set to true, mouse events will be intercepted by this frame, and will not be passed through, even if they are not handled by a script handler such as OnMouseDown.
  • frameLevel* - The level of the frame. This is the second most important factor in whether one widget is in front of another. This attribute is determined by the nesting of the tag. See Note on frameLevel.
  • frameStrata - The strata of the frame. This is the most important factor in whether one widget is in front of another. frameStrata is basically which layer your frame should be on. Valid values:
    • TOOLTIP
    • FULLSCREEN_DIALOG
    • FULLSCREEN
    • DIALOG
    • HIGH
    • MEDIUM
    • LOW
    • BACKGROUND
  • id - Number associated with the frame used in scripting to associate the widget with a Python object.
  • parent - Name of the parent of the window. Anchors will default to being relative to the parent, and if the parent is hidden, this widget will not be shown.


All widgets have these attributes that they inherit from Region:

  • hidden - Boolean; whether the widget is initially hidden.
  • inherits - name of the widget from which to inherit all attribute values. Must be widget of the same type as this widget (or an ancestor type).
  • name - name of the widget. The name must be unique across all widgets in the UI.
  • setAllPoints - Boolean (Not currently implemented)
  • virtual - Boolean; if true, indicates this widget is not actually created, but will be used as a template for other widgets.
[edit]

Property Elements

Button can contain these special property elements:

As a Frame, Button can contain any of these property elements:

Additionally, all widgets can contain these property elements:

  • Anchors - contains one or more Anchor elements that specify the positioning of the widget relative to its parent.
  • Size - specifies the size of the widget with an AbsDimension element.
[edit]

Methods

The following table describes the methods of the Button widget:

Method Description Parameters
Click() Execute the click action of the button. Trigger a click event on the button. None
Disable() Disable the button so that it cannot be clicked. This will generally cause the button to show up as disabled, and will prevent click events. None
Enable() Enable to the button so that it may be clicked. This will generally cause the button to show up as normal, and will allow click events. None
GetText() Returns the text associated with the button. None
GetTextHeight() Returns the line height of the text in the button. None
GetTextWidth() Returns the width of the text in the button. None
IsEnabled() Returns true if the button is enabled, false otherwise. None
LockHighlight() Lock highlight mode. Causes the button to show up as highlighted. None
SetButtonState(state) Set the button state state: one of "PUSHED" or "NORMAL"
SetButtonState(state, locked) Set the button state, and whether that state should be locked state: one of "PUSHED" or "NORMAL"

locked: true or a nonzero integer to lock the button in the specified state.

SetDisabledTextColor(red, green, blue) Set the color of the text for when the button is disabled. red: 0 to 1 value

green: 0 to 1 value
blue: 0 to 1 value

SetDisabledTexture(texture ) Set the texture to use when the button is disabled. texture - string identifying texture to use
SetHighlightTextColor(red, green, blue) Set the color of the text used when the button is highlighted. red: 0 to 1 value

green: 0 to 1 value
blue: 0 to 1 value

SetHighlightTexture(texture ) Set the texture to use when the button is highlighted. texture - string identifying texture to use
SetNormalTexture( texture ) Set the texture to use when the button is in normal mode. texture - string identifying texture to use
SetPushedTexture( texture ) Set the texture to use when the button is pushed. texture - string identifying texture to use
SetText( text ) Set the text to be displayed when the button is in normal mode text - text string
SetTextColor( red, green, blue ) Set the color of the text used when the button is in normal mode red: 0 to 1 value

green: 0 to 1 value
blue: 0 to 1 value

UnlockHighlight() Unlock the highlight mode. This will generally cause the button to show up as normal. Undoes the effect of LockHighlight() on the button. None


Methods Inherited from Frame
GetFrameLevel() Returns the Frame's frameLevel. See Note below.

Possbile values:

  • 0 - No parent
  • 1 - Parent is UIParent
  • 2 and higher...
None
GetFrameStrata() Get the frame strata of the frame. One of the following:
  • BACKGROUND
  • LOW
  • MEDIUM
  • HIGH
  • DIALOG
  • FULLSCREEN_DIALOG
  • TOOLTIP
None
GetID() Get the ID of the Frame (an integer). None
GetScript( handler ) Returns the function for the specified event handler.
HasScript( handler ) Returns true if the widget can be given a handler of the specified type (NOT whether it actually HAS one; use GetScript for that).
RegisterEvent( event ) Registers an events for the widget. See Client Event Handling. Name of the event to register.
SetBackdropColor(r, g, b, [a]) Sets the color value alpha values that tints the backdrop of a frame, as set by SetBackdrop([backdropTable]) method.

This color tints the Frame's backdrop file, which does not change the base color values of the file used, but rather modifies it. For example, tinting a black backdrop will have no effect. Alpha multiplies the existing alpha value. So, for example, an alpha of 1.0 for an image with an alpha channel of 0.5 shows the image with 50% opacity.

  • r: red value from 0 to 1
  • g: green value from 0 to 1
  • b: blue value from 0 to 1
  • a (optional): alpha value from 0 to 1 (transparent to opaque)
SetBackdropBorderColor(r, g, b, [a]) Sets the color of the border for the backdrop on a Frame.
  • r: red value from 0 to 1
  • g: green value from 0 to 1
  • b: blue value from 0 to 1
  • a (optional): alpha value from 0 to 1 (transparent to opaque)
SetFrameLevel( level ) Set the level of this frame (determines which of overlapping frames shows on top). Higher numbers always show up on top of lower numbers. Integer value. Possible values;
  • 0 - No parent
  • 1 - Parent is UIParent
  • 2 and higher...

See Note on frameLevel.

SetFrameStrata(strata) Set the frame strata of the frame. strata: the frame strata for the frame. One of the following:
  • BACKGROUND
  • LOW
  • MEDIUM
  • HIGH
  • DIALOG
  • FULLSCREEN_DIALOG
  • TOOLTIP
SetID(id) Set the ID of the Frame to be used in scripting. Number
SetScript( handler, func ) Set the specified function as the event handler for the wdiget. handler: String that specifies the handler to which to attach the function (for example, "OnShow", "OnEvent").

func: Function - The function to call. Use nil to remove the handler. func is called with arguments (frame, event). See Event handler arguments for more information.

UnregisterEvent( event ) Unregisters an event that the object is currently monitoring. Name of the event to unregister.
Methods Inherited from Region
ClearAllPoints() Clears all the anchors for the widget None
GetAlpha() Returns the opacity (alpha) of the texture object, from 0 to 1. This does not include the effect of the alpha values of the parent widgets. None
GetBottom() Returns the y coordinate of the bottom edge of the frame. NOTE: This method is available on FontString and Texture widgets only with 1.5. None
GetHeight() Returns the height of the widget None
GetLeft() Returns the x coordinate of the left edge of the frame.

NOTE: This method is available on FontString and Texture widgets only with 1.5.

None
GetName() Returns the name of the widget. None
GetParent() Returns the parent widget of the frame. NOTE: This method is available on FontString and Texture widgets only with 1.5. None
GetRight() Returns the x coordinate of the right edge of the frame. NOTE: This method is available on FontString and Texture widgets only with 1.5. None
GetTop() Returns the y coordinate of the top of the frame, but inverted so that 0 is the bottom of the screen. NOTE: This method is available on FontString and Texture widgets only with 1.5. None
GetWidth() Returns the width of the widget None
Hide() Mark the widget as hidden. If the widget, or any of the widget's parents are hidden, the widget will not be displayed. None
IsVisible() Returns true if the widget is visible, false otherwise. If the widget, or any of the widget's parents are hidden, the widget will not be displayed. None
SetAlpha(alpha) Set the alpha value (opacity) of the widget. alpha - a measure of opacity: zero (0) means transparent, while one (1) means opaque.
SetHeight(height) Set the height of the widget. height -height in pixels (integer)
SetPoint( point,

relativeTo,
relativePoint
[, xOffset, yOffset] )

Set an anchor point for the widget. Valid values for point and relativePoint arguments:
  • "TOPLEFT"
  • "TOPRIGHT"
  • "BOTTOMLEFT"
  • "BOTTOMRIGHT"
  • "TOP"
  • "BOTTOM"
  • "LEFT"
  • "RIGHT"
  • "CENTER"
point - Point on the widget that is anchored.

relativeTo - Name of the widget being achored to.
relativePoint - Point on the target being anchored to.
xOffset - Horizontal offset in pixels from the target (optional)
yOffset - Vertical offset in pixels from the target (optional). Higher points on the screen have a larger yOffset.
NOTE: You must specify both xOffset and yOffset or neither.

SetWidth(width) Set the width of the widget width - width in pixels(integer)
Show() Mark the widget as visible. If the widget, or any of the widget's parents are hidden, the widget will not be displayed. None


[edit]

Event Handlers


Event Handler Called When...
OnClick User clicks on the Button.
OnDoubleClick User double-clicks on the Button.
Event Handlers inherited from Frame
OnDragStart User starts drag action. Not called by the input handler.
OnDragStop User stops drag action. Not called by the input handler.
OnEnter The mouse pointer moves over the widget.
OnEvent Any other event occurs.
OnHide Widget is hidden.
OnKeyDown User presses any key down.
OnKeyUp User releases any key.
OnLeave The mouse pointer leaves the widget.
OnLoad Widget is loaded.
OnMouseDown User presses mouse button down when the pointer is over the widget.
OnMouseUp User releases mouse button when the pointer is over the widget.
OnMouseWheel User moves mouse wheel when the pointer is over the widget.
OnReceiveDrag User drags an object onto the widget. Not called by the input handler.
OnShow Widget is shown (un-hidden).
OnSizeChanged Widget's size changes. Not called by the input handler.
OnUpdate Called before each frame is painted (between the processing of events and user actions, but before the UI elements are drawn onto the screen). It is invoked for every visible widget that declares an OnUpdate handler.
[edit]

Example

 <Button name="AddButton" text="Add">
   <NormalText inherits="NormalFont" justifyH="CENTER" justifyV="MIDDLE">
     <Color r="1.0" g="1.0" b="1.0" a="1.0"/>
   </NormalText>
   <Size>
     <AbsDimension x="60" y="40"/>
   </Size>
   <Anchors>
     <Anchor point="BOTTOMLEFT" relativePoint="BOTTOMLEFT">
       <Offset> <AbsDimension x="30" y="0"/> </Offset>
     </Anchor>
   </Anchors>
   <NormalTexture file="Interface\MvButtons\Mv-Panel-Button-Up"/>
   <Scripts language="python">
     <OnClick>AddButton_OnClick( this ) </OnClick>
   </Scripts>
 </Button>
Retrieved from "http://update.multiverse.net/wiki/index.php/Button"
Personal tools