guicomponents

## Class GButton

- java.lang.Object
- - guicomponents.GComponent
  - - guicomponents.GButton

- All Implemented Interfaces:
    GConstants, Comparable<Object>, PConstants

      public class GButton
      extends GComponent

  This class is the Button component. The button face can have either text or an image or both just pick the right constructor. Three types of event can be generated :-
  PRESSED RELEASED CLICKED
  To simplify event handling the button only fires off CLICKED events if the mouse button is pressed and released over the button face (the default behaviour).
  Using

      button1.fireAllEvents(true);

  enables the other 2 events for button button1. A PRESSED event is created if the mouse button is pressed down over the button face, the CLICKED event is then generated if the mouse button is released over the button face. Releasing the button off the button face creates a RELEASED event.
  The image file can either be a single image which is used for all button states, or be a composite of 3 images (tiled horizontally) which are used for the different button states OFF, OVER and DOWN in which case the image width should be divisible by 3.
  A number of setImages(...) methods exist to set button state images, these can be used once the button is created.
  Author:
    Peter Lager

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class guicomponents.GComponent

      `GComponent.Z_Order`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DOWN`
    `static int` | `OFF`
    `static int` | `OVER`

    - ### Fields inherited from class guicomponents.GComponent

      `eventType, fGlobalFont, globalColor, globalColorScheme, globalFont, localColor, localFont, tag, tagNo, z`

    - ### Fields inherited from interface processing.core.PConstants

      `ADD, ALPHA, ALPHA_MASK, ALT, AMBIENT, ARC, ARGB, ARROW, BACKSPACE, BASELINE, BEVEL, BEZIER_VERTEX, BLEND, BLUE_MASK, BLUR, BOTTOM, BOX, BREAK, BURN, CENTER, CHATTER, CLAMP, CLOSE, CODED, COMPLAINT, CONTROL, CORNER, CORNERS, CROSS, CURVE_VERTEX, CUSTOM, DARKEST, DEG_TO_RAD, DELETE, DIAMETER, DIFFERENCE, DILATE, DIRECTIONAL, DISABLE_ACCURATE_2D, DISABLE_ACCURATE_TEXTURES, DISABLE_DEPTH_MASK, DISABLE_DEPTH_SORT, DISABLE_DEPTH_TEST, DISABLE_NATIVE_FONTS, DISABLE_OPENGL_ERRORS, DISABLE_STROKE_PERSPECTIVE, DISABLE_TEXTURE_CACHE, DISABLE_TEXTURE_MIPMAPS, DISABLE_TRANSFORM_CACHE, DODGE, DXF, ELLIPSE, ENABLE_ACCURATE_2D, ENABLE_ACCURATE_TEXTURES, ENABLE_DEPTH_MASK, ENABLE_DEPTH_SORT, ENABLE_DEPTH_TEST, ENABLE_NATIVE_FONTS, ENABLE_OPENGL_ERRORS, ENABLE_STROKE_PERSPECTIVE, ENABLE_TEXTURE_CACHE, ENABLE_TEXTURE_MIPMAPS, ENABLE_TRANSFORM_CACHE, ENTER, EPSILON, ERODE, ERROR_BACKGROUND_IMAGE_FORMAT, ERROR_BACKGROUND_IMAGE_SIZE, ERROR_PUSHMATRIX_OVERFLOW, ERROR_PUSHMATRIX_UNDERFLOW, ERROR_TEXTFONT_NULL_PFONT, ESC, EXCLUSION, GIF, GRAY, GREEN_MASK, GROUP, HALF_PI, HAND, HARD_LIGHT, HINT_COUNT, HSB, IMAGE, INVERT, JAVA2D, JPEG, LANDSCAPE, LEFT, LIGHTEST, LINE, LINE_LOOP, LINE_STRIP, LINES, LINUX, MACOSX, MAX_FLOAT, MAX_INT, MIN_FLOAT, MIN_INT, MITER, MODEL, MODELVIEW, MOVE, MULTIPLY, NORMAL, OPAQUE, OPEN, OPENGL, ORTHOGRAPHIC, OTHER, OVERLAY, P2D, P3D, PATH, PDF, PERSPECTIVE, PI, platformNames, POINT, POINTS, POLYGON, PORTRAIT, POSTERIZE, PROBLEM, PROJECT, PROJECTION, QUAD, QUAD_BEZIER_VERTEX, QUAD_STRIP, QUADS, QUARTER_PI, RAD_TO_DEG, RADIUS, RECT, RED_MASK, REPEAT, REPLACE, RETURN, RGB, RIGHT, ROUND, SCREEN, SHAPE, SHIFT, SOFT_LIGHT, SPHERE, SPOT, SQUARE, SUBTRACT, TAB, TARGA, TEXT, THIRD_PI, THRESHOLD, TIFF, TOP, TRIANGLE, TRIANGLE_FAN, TRIANGLE_STRIP, TRIANGLES, TWO_PI, UP, VERTEX, WAIT, WHITESPACE, WINDOWS, X, Y, Z`

    - ### Fields inherited from interface guicomponents.GConstants

      `ADD_DUPLICATE, BACKGROUND, CHANGED, CLICKED, CLOSE_WINDOW, COLLAPSED, CTRL_ANGULAR, CTRL_HORIZONTAL, CTRL_VERTICAL, DESELECTED, DISABLE_AUTO_DRAW, DRAGGED, ENTERED, EXCP_IN_HANDLER, EXIT_APP, EXPANDED, FAMILY, FOREGROUND, HUD_UNSUPPORTED, INVALID_STATUS, JUSTIFICATION, JUSTIFICATION_FULL, JUSTIFICATION_NONE, KEEP_OPEN, MISSING, NONEXISTANT, NOT_PEASYCAM, POSTURE, POSTURE_OBLIQUE, POSTURE_REGULAR, PRESSED, RELEASED, RUNTIME_ERROR, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHT, SCROLL_UP, SCROLLBAR_HORIZONTAL, SCROLLBAR_VERTICAL, SCROLLBARS_AUTOHIDE, SCROLLBARS_BOTH, SCROLLBARS_HORIZONTAL_ONLY, SCROLLBARS_NONE, SCROLLBARS_VERTICAL_ONLY, SELECTED, SET, SIZE, STRIKETHROUGH, STRIKETHROUGH_OFF, STRIKETHROUGH_ON, SUPERSCRIPT, SUPERSCRIPT_SUB, SUPERSCRIPT_SUPER, USER_COL_SCHEME, WEIGHT, WEIGHT_BOLD, WEIGHT_DEMIBOLD, WEIGHT_DEMILIGHT, WEIGHT_EXTRA_LIGHT, WEIGHT_EXTRABOLD, WEIGHT_HEAVY, WEIGHT_LIGHT, WEIGHT_MEDIUM, WEIGHT_REGULAR, WEIGHT_SEMIBOLD, WEIGHT_ULTRABOLD, WIDTH, WIDTH_CONDENSED, WIDTH_EXTENDED, WIDTH_REGULAR, WIDTH_SEMI_CONDENSED, WIDTH_SEMI_EXTENDED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GButton(PApplet theApplet, String text, int x, int y, int width, int height)` Create a button with text only.
    `GButton(PApplet theApplet, String imgFile, int nbrImages, int x, int y, int width, int height)` Create a button with image only.
    `GButton(PApplet theApplet, String text, String imgFile, int nbrImages, int x, int y, int width, int height)` Create a button with both text and image.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `draw()` Draw the button
    `void` | `fireAllEvents(boolean all)` If the parameter is true all 3 event types are generated, if false only CLICKED events are generated (default behaviour).
    `void` | `mouseEvent(MouseEvent event)` All GUI components are registered for mouseEvents.
    `void` | `setColorScheme(int schemeNo)` Set the color scheme for this button
    `void` | `setColours(int normal, int mouseOver, int pressed)` Set the colors to be used by the GButton without having to create a new color scheme (GCScheme).
    `void` | `setFont(String fontname, int fontsize)` Set the font & size for the button increasing height and width of the button if necessary to display text.
    `void` | `setFont(String fontname, int fontsize, boolean resize)` Set the font and size for the button.
    `void` | `setImageAlign(int imgAlign)` Sets the position of the image in relation to the button text provided the text horizontal alignment is GAlign.LEFT or GAlign.RIGHT
    `void` | `setImages(PImage[] images)` Specify the 3 images to be used to display the button's state.
    `void` | `setImages(PImage img, int nbrImages)` Specify the PImage that contains the image{s} to be used for the button's state.
    `void` | `setImages(PImage imgNormal, PImage imgOver, PImage imgPressed)` Specify the 3 images to be used to display the button's state.
    `void` | `setImages(String[] imgFiles)` Specify the 3 images files to be used to display the button's state.
    `void` | `setImages(String imgFile, int nbrImages)` Specify the image file that contains the image{s} to be used for the button's state.
    `void` | `setImages(String ifileNormal, String ifileOver, String ifilePressed)` Specify the 3 images files to be used to display the button's state.
    `void` | `setText(String text)` Set the text to appear on the button.

    - ### Methods inherited from class guicomponents.GComponent

      `add, addAbsoluteControl, addCompoundControl, addEventHandler, addEventHandler, addRelativeControl, addXXX, calcAbsPosition, changeWindow, compareTo, contains, ctrlMode, dispose, getAlpha, getBorder, getCtrlMode, getEventType, getFocusObject, getHeight, getOpaque, getPApplet, getParent, getStyledText, getText, getTransform, getWidth, getX, getY, hasFocus, hasKeyFocus, isEnabled, isOver, isVisible, keyPressed, pre, remove, setAlpha, setBorder, setEnabled, setFocus, setFontNew, setFontNew, setHeight, setLocalColorScheme, setOpaque, setRotation, setText, setTextAlign, setTextNew, setTextNew, setVisible, setWidth, setX, setXY, setY, toString`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### OFF

          public static final int OFF

      See Also:
        Constant Field Values

    - #### OVER

          public static final int OVER

      See Also:
        Constant Field Values

    - #### DOWN

          public static final int DOWN

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### GButton

          public GButton(PApplet theApplet,
                 String text,
                 int x,
                 int y,
                 int width,
                 int height)

      Create a button with text only. Height and width may increase depending on initial text a
      Parameters:
        `theApplet` -
        `text` - text appearing on the button
        `x` - horz position of button
        `y` - vert position
        `width` - minimum width of button
        `height` - minimum height of button

    - #### GButton

          public GButton(PApplet theApplet,
                 String imgFile,
                 int nbrImages,
                 int x,
                 int y,
                 int width,
                 int height)

      Create a button with image only. Height and width may increase depending on image size.
      Parameters:
        `theApplet` -
        `imgFile` - filename of image to use on the button
        `nbrImages` - number of images in the film strip normally 1 or 3 (OFF OVER DOWN)
        `x` - horz position of button
        `y` - vert position
        `width` - minimum width of button
        `height` - minimum height of button

    - #### GButton

          public GButton(PApplet theApplet,
                 String text,
                 String imgFile,
                 int nbrImages,
                 int x,
                 int y,
                 int width,
                 int height)

      Create a button with both text and image. Height and width may increase depending on initial text length and image size.
      Parameters:
        `theApplet` -
        `text` - text appearing on the button
        `imgFile` - filename of image to use on the button
        `nbrImages` - number of images in the film strip normally 1 or 3 (OFF OVER DOWN)
        `x` - horz position of button
        `y` - vert position
        `width` - minimum width of button
        `height` - minimum height of button

  - ### Method Detail

    - #### setColours

          public void setColours(int normal,
                        int mouseOver,
                        int pressed)

      Set the colors to be used by the GButton without having to create a new color scheme (GCScheme). Use PApplet's color() method to calculate the color values to be passed.
      Parameters:
        `normal` -
        `mouseOver` -
        `pressed` -

    - #### setImages

          public void setImages(String ifileNormal,
                       String ifileOver,
                       String ifilePressed)

      Specify the 3 images files to be used to display the button's state.
      Parameters:
        `ifileNormal` -
        `ifileOver` -
        `ifilePressed` -

    - #### setImages

          public void setImages(String[] imgFiles)

      Specify the 3 images files to be used to display the button's state.
      Parameters:
        `imgFiles` - an array of filenames

    - #### setImages

          public void setImages(String imgFile,
                       int nbrImages)

      Specify the image file that contains the image{s} to be used for the button's state.
      This image may be a composite of 1 to 3 images tiled horizontally.
      Parameters:
        `imgFile` -
        `nbrImages` - in the range 1 - 3

    - #### setImages

          public void setImages(PImage imgNormal,
                       PImage imgOver,
                       PImage imgPressed)

      Specify the 3 images to be used to display the button's state.
      Parameters:
        `imgNormal` -
        `imgOver` -
        `imgPressed` -

    - #### setImages

          public void setImages(PImage[] images)

      Specify the 3 images to be used to display the button's state.
      Parameters:
        `images` - an array of PImages

    - #### setImages

          public void setImages(PImage img,
                       int nbrImages)

      Specify the PImage that contains the image{s} to be used for the button's state.
      This image may be a composite of 1 to 3 images tiled horizontally.
      Parameters:
        `img` -
        `nbrImages` - in the range 1 - 3

    - #### setColorScheme

          public void setColorScheme(int schemeNo)

      Set the color scheme for this button
      Overrides:
        `setColorScheme` in class `GComponent`

    - #### setText

          public void setText(String text)

      Set the text to appear on the button. This does nothing if the parameter is null or an empty string.
      If the button has an image with CENTER allignment it is made LEFT alligment.
      Overrides:
        `setText` in class `GComponent`
      Parameters:
        `text` - the text to set with alignment

    - #### setFont

          public void setFont(String fontname,
                     int fontsize)

      Set the font & size for the button increasing height and width of the button if necessary to display text.
      It will not shrink if the font size is decreased.
      Overrides:
        `setFont` in class `GComponent`
      Parameters:
        `fontname` - the name of the font to use (if not available use default font)
        `fontsize` - the font size to use

    - #### setFont

          public void setFont(String fontname,
                     int fontsize,
                     boolean resize)

      Set the font and size for the button. If resize is true then the button size will be increased if necessary to display text.
      Parameters:
        `fontname` - the name of the font to use (if not available use default font)
        `fontsize` - the font size to use
        `resize` -

    - #### setImageAlign

          public void setImageAlign(int imgAlign)

      Sets the position of the image in relation to the button text provided the text horizontal alignment is GAlign.LEFT or GAlign.RIGHT
      Parameters:
        `imgAlign` - either GAlign.LEFT or GAlign.RIGHT

    - #### draw

          public void draw()

      Draw the button
      Overrides:
        `draw` in class `GComponent`

    - #### fireAllEvents

          public void fireAllEvents(boolean all)

      If the parameter is true all 3 event types are generated, if false only CLICKED events are generated (default behaviour).
      Parameters:
        `all` -

    - #### mouseEvent

          public void mouseEvent(MouseEvent event)

      All GUI components are registered for mouseEvents.
      When a button is clicked on a GButton it generates 3 events (in this order) mouse down, mouse up and mouse pressed.
      You can test for a particular event type with :

                  void handleButtonEvents(GButton button) {
                    if(button == btnName && button.eventType == GButton.PRESSED){
                  // code for button click event
              }

      Where

          btnName

      is the GButton identifier (variable name)
      If you only wish to respond to button click events then use the statement

          btnName.fireAllEvents(false);

      This is the default mode.
      Overrides:
        `mouseEvent` in class `GComponent`

Processing library guicomponents by Peter Lager. (C) 2012