mkv.MyGUI
Class MyGUITextInput
java.lang.Object
mkv.MyGUI.MyGUIObject
mkv.MyGUI.MyGUITextInput
- public class MyGUITextInput
- extends MyGUIObject
Visual GUI element for receiving and storing typed characters.
A MyGUITextInput object allows a user to enter in text to a program in a visual manner
within a confined space, defined by the _width and _height parameters.
The default _width is set to 100 pixels whilst the _height will vary depending on the
font size defined in the MyGUIStyle inherited by this object.
Bear in mind that this is a cut down text field object compared to what most users
are used to. It currently supports all ASCII characters, Backspace, Delete, Home, End,
Left and Right keys which all perform to the normal standards. It also supports clicking
to place the key cursor inbetween two characters. Highlighting multiple letters does NOT
work, and neither do the Copy, Cut or Paste commands.
Pressing ENTER while this object has focus will generate a MyGUIActionEvent in the
root processing applet.
MyGUITextInput objects inherit all the basic properties and methods from MyGUIObject,
The _x and _y coordinates specify the center of the text input box, and act as the rotation
and scale point when the object is drawn to the screen.
The text input uses all its colours from MyGUIStyle. In particular it uses the
MyGUIStyle.scrollBar colour as the light coloured background on which text is drawn.
The text colour is MyGUIStyle.buttonText. Please ensure that these two colours have
suitable contrast when customizing the colours.
- 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. |
java.lang.String |
_text
the visible portion of text to be rendered. |
java.lang.String |
_value
full text data stored by the text input |
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 |
MyGUITextInput(processing.core.PApplet root,
int x,
int y)
Most basic constructor, creates a default sized text area on the screen |
MyGUITextInput(processing.core.PApplet root,
int x,
int y,
int width,
int height)
This version lets you specify the width and height of the text box directly. |
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()
Draw methods for the object based on the object's various states. |
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. |
java.lang.String |
getValue()
Gets the text String value of the text input. |
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)
Detects when a non ascii key code is pressed. |
void |
keyReleased(java.awt.event.KeyEvent e)
When a key is released the keyPressed value is set to false. |
void |
keyTyped(java.awt.event.KeyEvent e)
Detects when an ascii key is typed on the keyboard. |
void |
mouseDragged()
Interface method. |
void |
mousePressed()
Called when a mouse is pressed on top of the object giving it 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 |
setValue(java.lang.String text)
Sets the text String value of the text input. |
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 |
_value
public java.lang.String _value
- full text data stored by the text input
_text
public java.lang.String _text
- the visible portion of text to be rendered. Always derived from _value.
_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
MyGUITextInput
public MyGUITextInput(processing.core.PApplet root,
int x,
int y)
- Most basic constructor, creates a default sized text area on the screen
- Parameters:
root
- The PApplet parent where this item will be drawnx
- the x coordinate of the text inputy
- the y coordinate of the text input
MyGUITextInput
public MyGUITextInput(processing.core.PApplet root,
int x,
int y,
int width,
int height)
- This version lets you specify the width and height of the text box directly.
- Parameters:
root
- The PApplet parent where this item will be drawnx
- x coordinate of the text inputy
- y coordinate of the text inputwidth
- width of the text inputheight
- height of the text input
setValue
public void setValue(java.lang.String text)
- Sets the text String value of the text input.
- Parameters:
text
- the new text to be stored in the text field.- See Also:
_text
getValue
public java.lang.String getValue()
- Gets the text String value of the text input.
- Returns:
- returns the String stored by the text input.
- See Also:
_text
mousePressed
public void mousePressed()
- Called when a mouse is pressed on top of the object giving it focus. Enables the
dragged state and displays the cursor next to the nearest letter in the text field
by calling updateText().
- Overrides:
mousePressed
in class MyGUIObject
- See Also:
MyGUIObject.mouseReleased()
,
MyGUIObject.mouseDragged()
keyPressed
public void keyPressed(java.awt.event.KeyEvent e)
- Detects when a non ascii key code is pressed. This method currently processes
The HOME and END keys moving the cursor to the start/end of the text, and also
the LEFT and RIGHT keys allowing a user to scroll back and forth inside the text
input. It displays the cursor while these buttons are pressed and calls updateText()
to update the visible text and the cursor position.
- Overrides:
keyPressed
in class MyGUIObject
- See Also:
KeyEvent.getKeyCode()
keyTyped
public void keyTyped(java.awt.event.KeyEvent e)
- Detects when an ascii key is typed on the keyboard. These characters are then added
to the string value stored by the text input. This method also supports BACK SPACE
removing a character before the cursor and DELETE removing the character after the
cursor. It also handles the ENTER key by creating an ActionEvent in the _root
applet. Any other key is added to the string just after the cursor.
- Overrides:
keyTyped
in class MyGUIObject
- See Also:
KeyEvent.getKeyChar()
,
_value
keyReleased
public void keyReleased(java.awt.event.KeyEvent e)
- When a key is released the keyPressed value is set to false.
- Overrides:
keyReleased
in class MyGUIObject
- See Also:
keyPressed(java.awt.event.KeyEvent)
drawStates
public void drawStates()
- Draw methods for the object based on the object's various states. This method
draws the text input on to the screen, called automatically by the draw() method.
It first draws the background box based on state, then draws the cursor and finally
renders the text to the screen.
- Overrides:
drawStates
in class MyGUIObject
- See Also:
MyGUIStyle
,
MyGUIObject.isDisabled()
,
MyGUIObject.hover
,
MyGUIObject.hasFocus()
,
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()
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.
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 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:
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