guicomponents

## Class GWSlider

- java.lang.Object
- - guicomponents.GComponent
  - - guicomponents.GSlider
    - - guicomponents.GWSlider

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

      public class GWSlider
      extends GSlider

  GWSlider is a wrapper class that extends the functionality of the gui4processing(g4p) slider. It adds a lot of functionality that is found in many other main stream sliders in other frameworks.

  The main change to the g4p slider was to introduce a more flexible and graphical interface to render the slider. The method used to render the slider is combining several images that relate to various segments of the slider in the form of a skin. The slider is broken down into 4 segments, each having a specific image file that relates to them:

  - Left end cap of the slider(end_left.png)
  - Right end cap of the slider(end_right.png)
  - An extendible centre segment(centre.png)
  - Draggable thumb (handle.png and handle_mouseover.png)

  The five images stated above define the skin that is applied to slider. A default skin is included in the library and applied when no other alternative is provided. To generate a skin all these images must be included into a folder in the sketches data directory, where the name of the folder is the name of the skin. When creating a new slider, there is a constructor available that allows you to specify the skin to use. Eg, if you have a folder name 'ShinyRedSkin' in your data directory that has the above images in, then pass a string with "ShinyRedSkin" to the constructor.

  The images need to related. The end_left, end_right and centre png's must all be the same height. The height can be whatever is required, though values round 20 is recommended. The end segments can both be different lengths and the length of the centre images must be 1 pixel. The centre image is stretched depending on the length of the slider to fill in the middle section. The thumb/handle can be any height and width but should be an odd number of pixels. An odd number allows a perfect centre to be found as fractional pixels are not possible. Alpha channel use is recommended to generate interesting skins.

  Also added to the slider is tick marks. The number of ticks shown is customisable and there is the option to stick the thumb to each tick. This only allows the thumb to take on certain values and positions. The ticks by default have only 2 labels, one showing the minimum and one the maximum. The other options are to have no tick labels or to specify a string array containing the labels.

  One of the more trickier features of the slider to understand is setting the type of the slider. By default the slider is set up to display and use integer values. On occasion it is useful to be able to specify a floating value range. When the slider is set to ValueType.Integer, any limits or values passed to the slider will be rounded to the nearest integer. If you later then switch to ValueType.Decimal or Exponential the limits and value will still be rounded. This can cause issues as the initial setting is ValueType.Integer, if you first set your floating limits and value then specify the type of the slider to be decimal, the decimal parts of the inputs will be lost. Always specify the ValueType of the slider as soon as it is created, this will save many headaches.

  Another confusing feature to the slider is the methods to retrieve the value of the slider. Initially the g4p slider only allowed an integer value. To get around this a new value member is defined as a float, where all the relevant methods are overridden to use this new value but to also update the old integer value. Unfortunately the getValue method is already predefined to return and integer, so a new getValuef() method is added to allow you to access the floating member. Either can be used but remember getValue() will always return a rounded value.

  The slider can also be controlled via the arrow keys on the keyboard for a finer adjustment. The slider must first have been given focus with the mouse before hand, before it will work.

  NOTE: Handle/Thumb image should be an odd number of pixels wide so that it can correctly centre on tick marks.

  History
  Version 0.3.3 overhaul to how ticks are calculated and rendered, firstly calculating the difference in value between tick and then relating that into a distance in pixels, rather than dividing length of slider by tick number.

  Author:
    Daniel Brown 21/6/09

- - ### Nested Class Summary

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

      `GComponent.Z_Order`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `String` | `unit`

    - ### Fields inherited from class guicomponents.GSlider

      `DECIMAL, EXPONENT, INTEGER`

    - ### 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, DOWN, 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
    `GWSlider(PApplet theApplet, int x, int y, int length)` basic constructor that applies the default library skin to the slider.
    `GWSlider(PApplet theApplet, String skin, int x, int y, int length)` Alternative constructor that applies a given skin to the slider.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `draw()` Override in child classes
    `boolean` | `isOver(int ax, int ay)` returns whether the positions supplied is over the mouse or not
    `boolean` | `isOverThumb(int ax, int ay)` return whether input position is over the thumb, used to determine whether to show the handle_mouseover image
    `void` | `keyEvent(KeyEvent e)` Registered key event of parent object, checks if arrow keys are being pressed and has focus if so the thumb is moved one pixel.
    `void` | `mouseEvent(MouseEvent event)` handles all the mouse events that may effect the slider.
    `void` | `setFont(String fontname, int fontsize)` Sets font of labels
    `void` | `setFontColour(int c)` Set the colour of the font
    `void` | `setFontColour(int R, int G, int B)` Set the colour of the font
    `void` | `setPrecision(int acc)` Sets the number of decimal places to print in the value labels
    `void` | `setRenderMaxMinLabel(boolean showMinMax)` set to false to not render the min/max labels for a more minamalistic look.
    `void` | `setRenderValueLabel(boolean showValue)` set to false to not render the value label for a more minamalistic look.
    `void` | `setStickToTicks(boolean stick)` Setting to true limits the thumb to only take values that each tick represents and no value in between them
    `void` | `setTickColour(int c)` Set the colour of the ticks
    `void` | `setTickColour(int R, int G, int B)` Set the colour of the ticks
    `void` | `setTickCount(int nbrTicks)` Sets the number of ticks shown on the slider.
    `void` | `setTickLabels(String[] lbls)` Accepts an array of strings that then determines the number of ticks shown and the label underneath each of them.
    `void` | `setTickLength(int l)` Adjusts the length of the ticks
    `void` | `setValue(float newValue)` Sets the target value of the slider, if setInertia(x) has been to implement inertia then the actual slider value will gradually change until it reaches the target value.
    `void` | `setValue(int newValue)` Sets the target value of the slider, if setInertia(x) has been used to implement inertia then the actual slider value will gradually change until it reaches the target value.
    `void` | `setValueToTickNumber(int tickNo)` Sets the target value of the slider according to the tick number.

    - ### Methods inherited from class guicomponents.GSlider

      `getMaxValue, getMinValue, getValue, getValuef, getValueType, isValueChanging, pre, setInertia, setLimits, setLimits, setValue, setValue, setValueType`

    - ### 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, isVisible, keyPressed, remove, setAlpha, setBorder, setColorScheme, setEnabled, setFocus, setFontNew, setFontNew, setHeight, setLocalColorScheme, setOpaque, setRotation, setText, 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

    - #### unit

          public String unit

  - ### Constructor Detail

    - #### GWSlider

          public GWSlider(PApplet theApplet,
                  int x,
                  int y,
                  int length)

      basic constructor that applies the default library skin to the slider. Accepts the x and y position of the slider, the PApplet theApplet where the slider is rendered and the length of the slider.
      Parameters:
        `theApplet` -
        `x` -
        `y` -
        `length` -

    - #### GWSlider

          public GWSlider(PApplet theApplet,
                  String skin,
                  int x,
                  int y,
                  int length)

      Alternative constructor that applies a given skin to the slider. Accepts the x and y position of the slider, the PApplet theApplet where the slider is rendered and the length of the slider. Throws GUIException if the necessary skin images are not present.
      Parameters:
        `theApplet` -
        `x` -
        `y` -
        `length` -

  - ### Method Detail

    - #### setPrecision

          public void setPrecision(int acc)

      Sets the number of decimal places to print in the value labels

    - #### setValue

          public void setValue(int newValue)

      Sets the target value of the slider, if setInertia(x) has been used to implement inertia then the actual slider value will gradually change until it reaches the target value. The slider thumb is always in the right position for the current slider value.
      Note that events will continue to be generated so if this causes unexpected behaviour then use setValue(newValue, true)
      Overrides:
        `setValue` in class `GSlider`
      Parameters:
        `newValue` - the value we wish the slider to become

    - #### setValue

          public void setValue(float newValue)

      Sets the target value of the slider, if setInertia(x) has been to implement inertia then the actual slider value will gradually change until it reaches the target value. The slider thumb is always in the right position for the current slider value.
      Note that events will continue to be generated so if this causes unexpected behaviour then use setValue(newValue, true)
      Overrides:
        `setValue` in class `GSlider`
      Parameters:
        `newValue` - the value we wish the slider to become

    - #### setValueToTickNumber

          public void setValueToTickNumber(int tickNo)

      Sets the target value of the slider according to the tick number. If setInertia(x) has been to implement inertia then the actual slider value will gradually change until it reaches the target value. The slider thumb is always in the right position for the current slider value.
      Note that events will continue to be generated so if this causes unexpected behaviour then use setValue(newValue, true)
      Parameters:
        `tickNo` - >=0 and < number of ticks

    - #### setTickCount

          public void setTickCount(int nbrTicks)

      Sets the number of ticks shown on the slider. This will cancel any labels previously set.

    - #### setTickLabels

          public void setTickLabels(String[] lbls)

      Accepts an array of strings that then determines the number of ticks shown and the label underneath each of them. This overrides any previous setting of the tick count and value label rendering.
      Parameters:
        `lbls` -

    - #### setStickToTicks

          public void setStickToTicks(boolean stick)

      Setting to true limits the thumb to only take values that each tick represents and no value in between them

    - #### setTickLength

          public void setTickLength(int l)

      Adjusts the length of the ticks
      Parameters:
        `l` -

    - #### setRenderMaxMinLabel

          public void setRenderMaxMinLabel(boolean showMinMax)

      set to false to not render the min/max labels for a more minamalistic look.

    - #### setRenderValueLabel

          public void setRenderValueLabel(boolean showValue)

      set to false to not render the value label for a more minamalistic look.

    - #### setTickColour

          public void setTickColour(int R,
                           int G,
                           int B)

      Set the colour of the ticks
      Parameters:
        `R` - red (0-255)
        `G` - green (0-255)
        `B` - blue (0-255)

    - #### setTickColour

          public void setTickColour(int c)

      Set the colour of the ticks
      Parameters:
        `c` - the colour value as calculated by the PApplet color() method.

    - #### setFontColour

          public void setFontColour(int R,
                           int G,
                           int B)

      Set the colour of the font
      Parameters:
        `R` - red (0-255)
        `G` - green (0-255)
        `B` - blue (0-255)

    - #### setFontColour

          public void setFontColour(int c)

      Set the colour of the font
      Parameters:
        `c` - the colour value as calculated by the PApplet color() method.

    - #### mouseEvent

          public void mouseEvent(MouseEvent event)

      handles all the mouse events that may effect the slider. depending on mouse position and action the focus is set to the slider and the relevant function and members set.
      Overrides:
        `mouseEvent` in class `GSlider`

    - #### keyEvent

          public void keyEvent(KeyEvent e)

      Registered key event of parent object, checks if arrow keys are being pressed and has focus if so the thumb is moved one pixel.

    - #### isOver

          public boolean isOver(int ax,
                       int ay)

      returns whether the positions supplied is over the mouse or not
      Overrides:
        `isOver` in class `GSlider`
      Parameters:
        `ax` - mouse x position
        `ay` - mouse y position
      Returns:
        always false

    - #### isOverThumb

          public boolean isOverThumb(int ax,
                            int ay)

      return whether input position is over the thumb, used to determine whether to show the handle_mouseover image
      Parameters:
        `ax` -
        `ay` -
      Returns:
        true if the position ax,ay is over the thumb

    - #### setFont

          public void setFont(String fontname,
                     int fontsize)

      Sets font of labels
      Overrides:
        `setFont` in class `GComponent`

    - #### draw

          public void draw()

      Description copied from class: `GSlider`
      Override in child classes
      Overrides:
        `draw` in class `GSlider`

Processing library guicomponents by Peter Lager. (C) 2012