mkv.MyGUI
Class MyGUIObject
java.lang.Object
mkv.MyGUI.MyGUIObject
- Direct Known Subclasses:
- MyGUIButton, MyGUICheckBox, MyGUIGroup, MyGUIImage, MyGUILabel, MyGUIPinSlider, MyGUITextInput
- abstract class MyGUIObject
- extends java.lang.Object
An interface for standardising the features of MyGUI components.
MyGUIObject is an interface for defining Graphical User Interface (GUI) objects for
Processing that are designed to work with the MyGUI collection class. Feel free t
extend this with your own GUI elements and send them to me for inclusion within the
library.
The MyGUIObject contains a standard set of variables and methods
which should be common amongst all MyGUIObjects. All interface objects, including
MyGUI stem from this class, it is at the top of the MyGUI hierachy. This change was
made so that any MyGUIObject could be the _parent of another MyGUIObject which was
important when developing MyGUIGroup.
The methods and variables defined below are meant to be useful and straight forward to
use.
- Author:
- John Beech
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. |
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. |
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 |
MyGUIObject(processing.core.PApplet root)
Most basic class constructor. |
MyGUIObject(processing.core.PApplet root,
int x,
int y)
Class constructor where the x and y coordinates can be specified. |
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 |
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 |
_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:
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:
_rotation
,
_scale
,
_width
,
_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:
_rotation
,
_scale
,
_width
,
_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:
_width
,
_height
,
_x
,
_y
,
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:
_width
,
_height
,
_x
,
_y
,
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:
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:
rotate(float)
,
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:
_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:
_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
,
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:
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:
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:
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:
checkForHit()
,
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:
hover
,
dragged
,
MyGUIButton
MyGUIObject
public MyGUIObject(processing.core.PApplet root)
- Most basic class constructor.
NOTE: There is no empty constructor, all classes that extend MyGUI must have a call
to super(root), supplying their own path to root. This is so they have access to the
correct draw methods within processing.
- Parameters:
root
- a direct reference to the main processing PApplet.
MyGUIObject
public MyGUIObject(processing.core.PApplet root,
int x,
int y)
- Class constructor where the x and y coordinates can be specified.
- Parameters:
root
- a direct reference to the main processing PApplet.x
- x coordinate of the objecty
- y coordinate of the object
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:
getFocusIndex()
,
MyGUIGroup.getFocusIndex()
,
_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:
_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:
hover
,
mousePressed()
,
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:
mouseReleased()
,
mouseDragged()
mouseReleased
public void mouseReleased()
- 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.
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:
drawStates()
,
_visible
drawStates
public void drawStates()
- 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:
- Default
- Disabled
- Focused Default
- Hover
- Focused Hover
- Dragged / Depressed
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.
- See Also:
MyGUIStyle
,
draw()
,
_disabled
,
hasFocus()
,
hover
,
dragged
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:
_id
,
hasFocus()
,
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
,
_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
,
_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:
disable()
,
_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:
enable()
,
_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:
_rotation
,
rotateRadians(float)
,
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:
_rotation
,
rotate(float)
,
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 normalizemin
- the minimum boundary valuemax
- 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:
_width
,
_height
,
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:
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
,
setStyle(MyGUIStyle)
,
_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:
hasFocus()
,
_id