mkv.MyGUI
Class MyGUIButton

java.lang.Object
  extended bymkv.MyGUI.MyGUIObject
      extended bymkv.MyGUI.MyGUIButton
Direct Known Subclasses:
MyGUIButtonDrag

public class MyGUIButton
extends MyGUIObject

This is the all encompasing and highly useful MyGUIButton class. It supports many constructors, and a variety of carefully worked out drawing methods.


Field Summary
 java.lang.String _actionCommand
          Description attached to an ActionEvent generated by the component.
 boolean _disabled
          Used to block mouse and key events.
 int _height
          Used to define the bounding box of an object.
 processing.core.PImage _icon
           
 int _id
          The id used to self check if the object has focus.
 MyGUIObject _parent
          The MyGUIObject which acts as the parent of this object.
 processing.core.PApplet _root
          A direct reference to the main processing PApplet.
 float _rotation
          The value in degrees defining the object rotation.
 float _scale
          Visual scale of the object.
 MyGUIStyle _style
          A reference to a MyGUIStyle object used in draw or for font metrics.
 java.lang.String _text
           
 boolean _visible
          The visibility and active state of the object.
 int _width
          Used to define the bounding box of an object.
 int _x
          Positional coordinate of the object.
 int _y
          Positional coordinate of the object.
protected  boolean dragged
          State where mouse is clicked and dragged across object.
protected  boolean hover
          State where mouse hovers over object.
protected  boolean lastHover
          State that changes when as a mouse moved outside bounding box.
 int tmouseX
          Local mouse coordinate based on parent.
 int tmouseY
          Local mouse coordinate based on parent.
 
Constructor Summary
MyGUIButton(processing.core.PApplet root, int x, int y)
           
MyGUIButton(processing.core.PApplet root, int x, int y, int width, int height)
           
MyGUIButton(processing.core.PApplet root, int x, int y, processing.core.PImage icon)
           
MyGUIButton(processing.core.PApplet root, int x, int y, java.lang.String text)
           
MyGUIButton(processing.core.PApplet root, int x, int y, java.lang.String text, int width, int height)
           
 
Method Summary
 boolean checkForHit()
          Defines the bounding box or 'hitzone' and returns true if the mouse is in contact.
 void disable()
          Disables this object so that it not longer receives mouse or keyboard events.
 void draw()
          Code peformed every frame in the main applet happens here.
 void drawStates()
          Interface method called by draw().
 void enable()
          Activates this object so it is able to receive mouse and keyboard events.
 int getFocusIndex()
          Returns -1, usually an invalid index.
 MyGUIStyle getStyle()
          Returns the currently assigned style.
 boolean hasFocus()
          Returns true if the object has focus.
 boolean isDisabled()
          Checks the _disabled variable and its parent.
 boolean isDragged()
          Returns constant state of mouse clicked compared to this object.
 void keyPressed(java.awt.event.KeyEvent e)
          Interface method.
 void keyReleased(java.awt.event.KeyEvent e)
          Interface method.
 void keyTyped(java.awt.event.KeyEvent e)
          Interface method.
 void mouseDragged()
          Interface method.
 void mousePressed()
          Sets dragged to true if object has focus.
 void mouseReleased()
          Sets dragged to false.
protected  float normalize(float n, float min, float max)
          Normalization function that ensures a value always lies within min/max.
 void rotate(float degs)
          Increases/decreases the _rotation attribute by the supplied amount.
 void rotateRadians(float rads)
          Increases/decreases the _rotation attribute by the given amount.
 void setActionCommand(java.lang.String command)
          Sets the descriptive action command when an ActionEvent is generated.
 void setID(int newID)
          Sets the unique id to the specified integer.
 void setLabel(java.lang.String label)
          Set the label text
 void setLabel(java.lang.String label, boolean fixedSize)
          Set the label text with additional var for user to choose whether they want the size to automatically adjust based on the font, or to stay at a fixed size, (compromising the hit check area) - but maintaining size.
 void setParent(MyGUIObject parent)
          Tells the object who its parent is.
 void setStyle(MyGUIStyle style)
          Sets a custom style for this object.
 void updateLocalMouse()
          Calculates the local relative mouse coordinates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_text

public java.lang.String _text

_icon

public processing.core.PImage _icon

_root

public processing.core.PApplet _root
A direct reference to the main processing PApplet. All drawing methods will be sent to to this object.


_parent

public MyGUIObject _parent
The MyGUIObject which acts as the parent of this object. Style, mouse coordinates, visibility and many other variables are inherited from a parent. Parents are not defined in the constructor, instead they must be set using the setParent() method.

See Also:
MyGUIObject.setParent(MyGUIObject parent)

_style

public MyGUIStyle _style
A reference to a MyGUIStyle object used in draw or for font metrics.


_x

public int _x
Positional coordinate of the object. The actual position will depend on the coordinates of parent objects. Parent objects can be translated, scaled and rotated. This means that the x,y coordinate is not an absolute screen position. The x,y coordinate normally define the rotation point of the object.

See Also:
MyGUIObject._rotation, MyGUIObject._scale, MyGUIObject._width, MyGUIObject._height

_y

public int _y
Positional coordinate of the object. The actual position will depend on the coordinates of parent objects. Parent objects can be translated, scaled and rotated. This means that the x,y coordinate is not an absolute screen position. The x,y coordinate normally define the rotation point of the object.

See Also:
MyGUIObject._rotation, MyGUIObject._scale, MyGUIObject._width, MyGUIObject._height

_width

public int _width
Used to define the bounding box of an object. Used both for drawing visual components such as the width and height of a button, and defining the default hit zone of an object. The value may not required in some objects, such as MyGUIGroup but is common in most elements.

See Also:
MyGUIObject._width, MyGUIObject._height, MyGUIObject._x, MyGUIObject._y, MyGUIObject.checkForHit()

_height

public int _height
Used to define the bounding box of an object. Used both for drawing visual components such as the width and height of a button, and defining the default hit zone of an object. The value may not required in some objects, such as MyGUIGroup but is common in most elements.

See Also:
MyGUIObject._width, MyGUIObject._height, MyGUIObject._x, MyGUIObject._y, MyGUIObject.checkForHit()

_id

public int _id
The id used to self check if the object has focus. The id is checked against a value in the parent to see if it has been granted focus. The object's id is commonly a reference to the index in MyGUIGroup elements[] where the object is grouped with other objects. In this situation _id is not unique. However, in programming more advanced grouping schemes this value may have a different role.

See Also:
MyGUIObject.hasFocus(), MyGUIGroup

_rotation

public float _rotation
The value in degrees defining the object rotation. This value is used to transform the drawing matrix and is used in updateLocalMouse(). It can be set directly or by using the rotateDegrees() and rotateRadians() methods.

See Also:
MyGUIObject.rotate(float), MyGUIObject.rotateRadians(float)

_scale

public float _scale
Visual scale of the object. Its default value is 1.0, increasing this makes the object look bigger on the screen, decreasing it makes it smaller. Negative values are allowed.


_visible

public boolean _visible
The visibility and active state of the object. True for visible, false for hidden. When hidden the object will not receive any mouse or key events, and so is practically disabled.

See Also:
MyGUIObject._disabled

_disabled

public boolean _disabled
Used to block mouse and key events. Set to true to disable an object, false for normal operation. When disabled an object should not receive any mouse or key events from its parents. It will still have its draw method called. To reflect the fact that it is disabled a draw state condition should be written to resemble something disabled and unoperable. MyGUIStyle contains a disabled colour which can be used to replace the face, or buttonFace colour in this situation.

See Also:
MyGUIObject._visible, MyGUIStyle.disabled

_actionCommand

public java.lang.String _actionCommand
Description attached to an ActionEvent generated by the component. If an object generates a MyGUIActionEvent then this string will be used for the Event's action command. It will be accessible by the ActionEvent.getActionCommand() method.

See Also:
MyGUIActionEvent, MyGUIObject.setActionCommand(String)

tmouseX

public int tmouseX
Local mouse coordinate based on parent. These integer coordinates reflect the local position of the mouse relative to where the object is now. They are calculated in the updateLocalMouse() method by looking at the parent's value and adjusting for _rotation, _scale and _x, _y translation.

See Also:
MyGUIObject.updateLocalMouse()

tmouseY

public int tmouseY
Local mouse coordinate based on parent. These integer coordinates reflect the local position of the mouse relative to where the object is now. They are calculated in the updateLocalMouse() method by looking at the parent's value and adjusting for _rotation, _scale and _x, _y translation.

See Also:
MyGUIObject.updateLocalMouse()

dragged

protected boolean dragged
State where mouse is clicked and dragged across object. Dragged is only set to true if the object has gained focus and the mouse has not yet been released. The instant that a user clicks inside the bounding box of the object dragged will be set. It is immediately unset on mouseRelease. The method isDragged() can be used to check this state in a program.

See Also:
MyGUIObject.isDragged()

hover

protected boolean hover
State where mouse hovers over object. The most accurate and current value for hover should be based off the boolean checkForHit() method. However, to minimise calls to this method the hover state can be used instead. A shape can be hovered and dragged at the same time.

See Also:
MyGUIObject.checkForHit(), MyGUIObject.lastHover

lastHover

protected boolean lastHover
State that changes when as a mouse moved outside bounding box. Although I've not implemented this anywhere yet, lastHover detected the change between a mouse hovering and not hovering. Important in conjunction with dragged because you may want a button to only respond if the mouse is released over the button as apposed to a user clicking, dragging, moving away from the button, and letting go. Its a fine line, but its actually a feature of most buttons that MyGUIButton neglects.

See Also:
MyGUIObject.hover, MyGUIObject.dragged, MyGUIButton
Constructor Detail

MyGUIButton

public MyGUIButton(processing.core.PApplet root,
                   int x,
                   int y)

MyGUIButton

public MyGUIButton(processing.core.PApplet root,
                   int x,
                   int y,
                   java.lang.String text)

MyGUIButton

public MyGUIButton(processing.core.PApplet root,
                   int x,
                   int y,
                   int width,
                   int height)

MyGUIButton

public MyGUIButton(processing.core.PApplet root,
                   int x,
                   int y,
                   java.lang.String text,
                   int width,
                   int height)

MyGUIButton

public MyGUIButton(processing.core.PApplet root,
                   int x,
                   int y,
                   processing.core.PImage icon)
Method Detail

setLabel

public void setLabel(java.lang.String label)
Set the label text

Parameters:
label - the new label

setLabel

public void setLabel(java.lang.String label,
                     boolean fixedSize)
Set the label text with additional var for user to choose whether they want the size to automatically adjust based on the font, or to stay at a fixed size, (compromising the hit check area) - but maintaining size.

Parameters:
label - the new label
fixedSize - stay at fixed width/height or dynamically adjust

mouseReleased

public void mouseReleased()
Description copied from class: MyGUIObject
Sets dragged to false. This is the most basic response to the mouse being released. If you want to do something fancy when the mouse is released then feel free to override this method in your own class. It is called by its parent every time the mouse is released.

Overrides:
mouseReleased in class MyGUIObject

drawStates

public void drawStates()
Description copied from class: MyGUIObject
Interface method called by draw(). If you using the default draw() method then all your draw code for objects should go in this drawStates() method. You should build in drawing routines for all the standard states. For a button there are six states that I have identified: There are a range of basic colours that can be used to visually identify these states to the end user. See the MyGUIStyle class for more details.

Overrides:
drawStates in class MyGUIObject
See Also:
MyGUIStyle, MyGUIObject.draw(), MyGUIObject._disabled, MyGUIObject.hasFocus(), MyGUIObject.hover, MyGUIObject.dragged

hasFocus

public boolean hasFocus()
Returns true if the object has focus. This method checks with its parent to see if this object has focus. If it doesn't, then it returns false. Compatable parent objects will keep a list of their children and which children have focus, this method calls _parent.getFocusIndex() and compares the focus index with the id/index of this object.

Returns:
returns true if the element has focus, false if it does not.
See Also:
MyGUIObject.getFocusIndex(), MyGUIGroup.getFocusIndex(), MyGUIObject._id

isDisabled

public boolean isDisabled()
Checks the _disabled variable and its parent. This maintains the hierarchical structure where disabling a parent will also indirectly disable its children.

Returns:
returns true if disabled, false if enabled (normal state).
See Also:
MyGUIObject._disabled

isDragged

public boolean isDragged()
Returns constant state of mouse clicked compared to this object. If the mouse is considered permenantly pressed or dragged. The state should only be initialised after the object has gained focus.

Returns:
returns true if clicked/dragged and false otherwise.
See Also:
MyGUIObject.hover, MyGUIObject.mousePressed(), MyGUIObject.hasFocus()

mousePressed

public void mousePressed()
Sets dragged to true if object has focus. This is the most basic response to a mouse click. Arguably it could generate an actionEvent as well if it had focus. This method can be easily overriden for custom handling of mouse events, specifically the mousePressed() event. It is called by its parent every time the mouse is pressed.

See Also:
MyGUIObject.mouseReleased(), MyGUIObject.mouseDragged()

mouseDragged

public void mouseDragged()
Interface method. It does nothing. When the mouse is dragged this method is called by the parent object. Useful for real time dragging. MyGUIButtonDrag uses this to update its _x and _y coordinates when the dragged state is set to true.


keyPressed

public void keyPressed(java.awt.event.KeyEvent e)
Interface method. Automatically called by the parent object when a key is pressed.


keyReleased

public void keyReleased(java.awt.event.KeyEvent e)
Interface method. Automatically called by the parent object when a key is released.


keyTyped

public void keyTyped(java.awt.event.KeyEvent e)
Interface method. Automatically called by the parent object when an ascii key is typed. e.getChar() can be used when this method is called.


draw

public void draw()
Code peformed every frame in the main applet happens here. This method recalls drawStates() based on visibility (_visible set to true). I would advise this function is not overriden. Instead, code for drawing objects based on the states (_disabled, dragged, hover, hasFocus()) should be added to the drawStates() method.

The method draw() contains a filter which prevents drawStates() from being called if _visible is set to false. This was introduced for easy encapsulation of the draw methods if any more logical conditions need be applied. This is a second stage filter infact. MyGUIGroup (the standard parent object) also checks _visibility when calling the draw method - other grouping objects in the future may not and so this is why there is a second filter here.

See Also:
MyGUIObject.drawStates(), MyGUIObject._visible

setID

public void setID(int newID)
Sets the unique id to the specified integer. This value usually matches the array entry of the parent object 'storing' it. The _id is used to check whether an element has focus or not. If the ID is not set it risks being considered as 0, and may accidently gain focus. If an element does not have a parent then it's _id should be set to -1 (an invalid array location).

Parameters:
newID - The new ID of the object.
See Also:
MyGUIObject._id, MyGUIObject.hasFocus(), MyGUIObject.getFocusIndex()

setParent

public void setParent(MyGUIObject parent)
Tells the object who its parent is. A new object must be told what its parent is using this method. I've done this to cut down on the number of variables people have to supply in the constructor.

Parameters:
parent - the parent MyGUIObject of this object. Usually a MyGUIGroup object.
See Also:
MyGUIGroup

setActionCommand

public void setActionCommand(java.lang.String command)
Sets the descriptive action command when an ActionEvent is generated. This method allows a user to set a custom action command string, for example on a button a user could set this to "Save". Later, when a MyGUIActionEvent is generated this string can be compared using if(e.getActionCommand().equals("Save")). This is most useful when you have several GUI elements that you want to execute the same piece of code by assinging them the same action command. Otherwise, it might be easier to use if(e.getSource() == button), providing you have itemized your elements in that format.

Parameters:
command - The string value used to identify this action command.
See Also:
MyGUIActionEvent, MyGUIObject._actionCommand

setStyle

public void setStyle(MyGUIStyle style)
Sets a custom style for this object. If you want to customise a specific object then you can create and modify new MyGUIStyle and apply it to an object. Applying this to a group object will affect the look and style of all its children.

Parameters:
style - A valid MyGUIStyle object.
See Also:
MyGUIStyle, MyGUIObject._style

enable

public void enable()
Activates this object so it is able to receive mouse and keyboard events. Its the opposite of disabled(). The method sets the _disabled attribute to false.

See Also:
MyGUIObject.disable(), MyGUIObject._disabled

disable

public void disable()
Disables this object so that it not longer receives mouse or keyboard events. Its counter method is enable. The attribute _disabled is used by MyGUIGroup to block mouseEvent and keyEvent methods from reaching an object. The draw methods of MyGUIObjects should reflect the disabled state by using the MyGUIStyle.disabled colour, which by default is a tinted greyed version of the buttonFace colour.

See Also:
MyGUIObject.enable(), MyGUIObject._disabled

rotate

public void rotate(float degs)
Increases/decreases the _rotation attribute by the supplied amount. You may also use guiObject._rotation += degs; since _rotation is a public variable. The value is always normalized to lie within 0 < angle < 360.

Parameters:
degs - the value in degrees to alter the rotation by
See Also:
MyGUIObject._rotation, MyGUIObject.rotateRadians(float), MyGUIObject.normalize(float, float, float)

rotateRadians

public void rotateRadians(float rads)
Increases/decreases the _rotation attribute by the given amount. It converts the supplied value from radians into degrees. The value is always normalized to lie within 0 < angle < 360.

Parameters:
rads - the value in radiands to alter the rotation by
See Also:
MyGUIObject._rotation, MyGUIObject.rotate(float), MyGUIObject.normalize(float, float, float)

normalize

protected float normalize(float n,
                          float min,
                          float max)
Normalization function that ensures a value always lies within min/max. Unlike PApplet.constrain this method will loop a value, like an angle 370 degrees will change to 10 degrees. This is the main intention for the method.

Parameters:
n - the number you want to normalize
min - the minimum boundary value
max - the maximum boundary value
Returns:
returns a normalized value that lies within min <= n <= max

checkForHit

public boolean checkForHit()
Defines the bounding box or 'hitzone' and returns true if the mouse is in contact. The method is used to check the hover state and whether the element can gain focus. This method calls updateLocalMouse() to set relative mouse coordinates tmouseX and tmouseY before peforming the check. You should write your own custom method if yo had an odd shaped shape that you want to calculate the position for.

This default checkForHit methods checks the bounding box of a shape (-width/2, _y-width/2, _width/2, _height/2) taking into account when rotatation and scale.

See Also:
MyGUIObject._width, MyGUIObject._height, MyGUIObject.updateLocalMouse()

updateLocalMouse

public void updateLocalMouse()
Calculates the local relative mouse coordinates. By local this means the tmouseX and tmouseY coordinates are set relative to the _x, _y position of this object. These are then used in public boolean checkForHit();

See Also:
MyGUIObject.checkForHit()

getStyle

public MyGUIStyle getStyle()
Returns the currently assigned style. Each MyGUIObject takes its own style object from its parent. This means that if you modify it for a single object you will probably affect the whole hierarchy. To change the specific style for a single object try creating a new MyGUIStyle variable and then use setStyle(MyGUIStyle)

Returns:
returns a reference to the currently assigned MyGUIStyle style
See Also:
MyGUIStyle, MyGUIObject.setStyle(MyGUIStyle), MyGUIObject._style

getFocusIndex

public int getFocusIndex()
Returns -1, usually an invalid index. Not all MyGUIObject's are designed to track children. The getFocusIndex is required so that children can check with their parent to see if they are selected. Classes extending MyGUIObject will have to override this method if they intend to support tracking the focus of their children - as well as having other capabilities.

Returns:
returns -1 always. Pretty boring really.
See Also:
MyGUIObject.hasFocus(), MyGUIObject._id