Package totalcross.ui

Class Button

  • All Implemented Interfaces:
    TextControl
    Direct Known Subclasses:
    ArrowButton, ShadedButton
    public class Button
extends Control
implements TextControl
    Button is a push button control. It supports multilined text, a standalone image, or text mixed with images. Image buttons have a fade look when not enabled. If you want a sticky button, set the isSticky field or use the PushButtonGroup class selecting the CHECK mode.

    Here is an example showing a push button being used: 

     public class MyProgram extends MainWindow
 {
    Button btn1,btn2;

    public void initUI()
    {
       add(btn1 = new Button("Push me\nPlease"), CENTER,TOP);
       add(btn2 = new Button(new Image("myimage.png")), CENTER,AFTER+3);
    }

    public void onEvent(Event event)
    {
       if (event.type == ControlEvent.PRESSED)
       {
          if (event.target == btn1)
          {
             ... handle btn1 being pressed

    • Field Detail

      • BORDER_NONE

        public static final byte BORDER_NONE
        Specifies no border for this button. Used in the setBorder method.
        See Also:
        Constant Field Values

      • BORDER_SIMPLE

        public static final byte BORDER_SIMPLE
        Specifies a single-lined border for this button. Used in the setBorder method.
        See Also:
        Constant Field Values

      • BORDER_3D

        public static final byte BORDER_3D
        Specifies a 3d border for this button. Used in the setBorder method.
        See Also:
        Constant Field Values

      • BORDER_3D_VERTICAL_GRADIENT

        public static final byte BORDER_3D_VERTICAL_GRADIENT
        Specifies a vertical 3d-gradient border for this button. Used in the setBorder method. Note that, in this mode, the back and fore colors are set using the borderColor3DG, topColor3DG and bottomColor3DG properties.
        See Also:
        Constant Field Values

      • BORDER_3D_HORIZONTAL_GRADIENT

        public static final byte BORDER_3D_HORIZONTAL_GRADIENT
        Specifies a horizontal 3d-gradient border for this button. Used in the setBorder method. Note that, in this mode, the back and fore colors are set using the borderColor3DG, topColor3DG and bottomColor3DG properties.
        See Also:
        Constant Field Values

      • BORDER_GRAY_IMAGE

        public static final byte BORDER_GRAY_IMAGE
        Specifies that the image passed in the constructor is a gray image that will be recolorized and resized to the text's size. To create the image that will work with this border type, do this:
        1. Get an empty image from somewhere in the web (this site is a good place; choose a light background image to prevent problems described in step 5).
        2. Do not resize the button.
        3. Convert the button to grayscale (you can download irfanview and choose menu Image / Convert to Grayscale
        4. When saving the image (as png), don't forget to save the transparent color (irfanview has an option to save it in the save dialog).
        5. Images with a smooth round border should have the background colorized to the target background color; otherwise, the results will not be perfect.

        Important: you must set the button colors before calling setBorder. Here's a sample: 

         Button btn = new Button("Bárbara\nHazan", new Image("button1.png"), CENTER, 8);
 btn.setBackColor(backColor);
 btn.borderColor3DG = 0x008800; // used to colorize the image
 btn.setBorder(Button.BORDER_GRAY_IMAGE);
 add(btn, CENTER, CENTER);
        Since:
        TotalCross 1.12
        See Also:
        Constant Field Values

      • BORDER_ROUND

        public static final byte BORDER_ROUND
        Specifies a rounded border for this button. Used in the setBorder method. Note that you MUST use PREFERRED when specifying button's height.
        Since:
        TotalCross 3.04
        See Also:
        roundBorderFactor, Constant Field Values

      • BORDER_OUTLINED

        public static final byte BORDER_OUTLINED
        Specifies a outlined border. Used in the setBorder method.
        See Also:
        Constant Field Values

      • drawBordersIfTransparentBackground

        public boolean drawBordersIfTransparentBackground
        Set to true to draw the button borders if transparentBackground is true.
        Since:
        TotalCross 1.15

      • currentFrame

        public int currentFrame
        The current frame in a multi-frame image.

      • shiftOnPress

        public boolean shiftOnPress
        Set to false to disable the button's shift when its pressed.

      • roundBorderFactor

        public int roundBorderFactor
        The factor by which the height will be divided to find the round border radius. Used when border is set to BORDER_ROUND.

      • disabledColor

        public int disabledColor
        Set the color for the control when it's disabled.

      • autoRepeat

        public boolean autoRepeat
        Set to true to enable auto-repeat feature for this button. The PRESSED event will be sent while this button is held.
        Since:
        TotalCross 1.22
        See Also:
        INITIAL_DELAY, AUTO_DELAY

      • INITIAL_DELAY

        public int INITIAL_DELAY
        The initial delay to start the auto-repeat. Defaults to 600ms.

      • AUTO_DELAY

        public int AUTO_DELAY
        The frequency in which the PRESSED event will be posted after the INITIAL_DELAY was reached. Defaults to 150ms.

      • text

        protected java.lang.String text

      • img

        protected Image img

      • img0

        protected Image img0

      • imgDis

        protected Image imgDis

      • armed

        protected boolean armed

      • border

        protected byte border

      • tx0

        protected int tx0

      • ty0

        protected int ty0

      • ix0

        protected int ix0

      • iy0

        protected int iy0

      • fColor

        protected int fColor

      • pressColor

        protected int pressColor

      • fourColors

        protected int[] fourColors

      • txtPos

        protected int txtPos

      • tiGap

        protected int tiGap

      • maxTW

        protected int maxTW

      • borderColor

        public int borderColor
        The border color.

      • paddingLeft

        public int paddingLeft
        Sets the left padding for this button.

      • paddingRight

        public int paddingRight
        Sets the right padding for this button.

      • paddingTop

        public int paddingTop
        Sets the top padding for this button.

      • paddingBottom

        public int paddingBottom
        Sets the bottom padding for this button.

      • lines

        protected java.lang.String[] lines

      • linesW

        protected int[] linesW

      • pressedImage

        public Image pressedImage
        Sets the image that will be displayed when the user press this button. Only works on Imaged buttons. Here's a sample: 
         Image img = btn.getImage();
 img = img.getFrameInstance(0); // gets a copy of the image
 img.applyColor(Color.RED); // colorize as red
 btn.pressedImage = img;
 // another option: btn.pressedImage = btn.getImage().getFadedInstance(Color.RED);
        Since:
        TotalCross 1.15

      • flatBackground

        public boolean flatBackground
        If ui style is vista and border is BORDER_NONE, setting this to false will make the button have a vista-like background. Otherwise, it will have a flat background.
        Since:
        TotalCross 1.0 beta 4.

      • cornerRadius3DG

        public int cornerRadius3DG
        The corner radius of this button when BORDER_3D_GRADIENT border style is active. Set to 10 when setBorder is called.

      • borderWidth3DG

        public int borderWidth3DG
        The border width of this button when BORDER_3D_GRADIENT border style is active. Set to 2 when setBorder is called.

      • borderColor3DG

        public int borderColor3DG
        The border color of this button when BORDER_3D_GRADIENT border style is active. Set to 0x00108A when setBorder is called.

      • topColor3DG

        public int topColor3DG
        The top color of this button when BORDER_3D_GRADIENT border style is active. Set to 0xDCDCFF when setBorder is called.

      • bottomColor3DG

        public int bottomColor3DG
        The bottom color of this button when BORDER_3D_GRADIENT border style is active. Set to Color.BLUE when setBorder is called.

      • hightlightColor

        @Deprecated
public int hightlightColor
        Deprecated.
        Fix the typo, use Control.textShadowColor instead.
        Change to a color value to highlight the button's text. The highlight is made drawing the button in x-1,y-1; x+1,y-1; x-1,y+1; x+1,y+1 positions. Defaults to -1.
        Since:
        TotalCross 1.12

      • commonGap

        public static int commonGap
        Set commonGap to a value to make all further buttons with the same internal gap. Remember to save the current value and restore it when done. Changing this also affects the size of the ScrollBars created. The value is stored locally on the constructor so it works later if the screen is resized.

      • isSticky

        public boolean isSticky
        Set to true to make this button sticky: it keeps pressed until the next click. Note that this disables autoRepeat.
        Since:
        TotalCross 1.25

      • relativeToText

        public java.lang.String relativeToText
        Used when the textPosition is RIGHT_OF. Specifies the text that will be used as reference to center this button's text with that one. Usually, you find the biggest text of a set of buttons and place it here.
        Since:
        TotalCross 1.27

      • underlinedText

        public boolean underlinedText
        Set to true to put a line under the text. Here's an example: 
         Button btLink;
 btLink = new Button("(Guide 124...)");
 btLink.underlinedText = true;
 btLink.setBorder(BORDER_NONE);
 btLink.setForeColor(Color.BLUE);
 add(btLink, LEFT, TOP, FILL, PREFERRED);
        Since:
        TotalCross 2.0

      • imageHeightFactor

        public int imageHeightFactor
        The height of the image based on the button's height, ranging from 1 to 100. Used when an image is passed as parameter in one of the constructors.

      • fillWhenPressedOnTransparentBackground

        public boolean fillWhenPressedOnTransparentBackground
        Fills the button when pressed even if transparentBackground is set.

    • Constructor Detail

      • Button

        public Button​(java.lang.String text,
              Image img,
              int textPosition,
              int gap)
        Creates a button that shows the given text and image.
        Parameters:
        text - The text to be displayed
        img - The image to be displayed
        textPosition - Where to place the text (supports only LEFT, TOP, RIGHT, BOTTOM, CENTER - no adjustments!). Also supports RIGHT_OF, which uses the relativeToText field as another button to be used as reference to be able to center the title among a set of buttons; the text will be placed at the right)
        gap - The space between the text and the image
        Since:
        TotalCross 1.0

      • Button

        public Button​(java.lang.String text)
        Creates a button displaying the given text.

      • Button

        public Button​(java.lang.String text,
              byte border)
        Creates a button displaying the given text and border.

      • Button

        public Button​(Image img)
        Creates a button with the given image. The transparentColor property of the Image must be set before calling this constructor.

      • Button

        public Button​(Image img,
              byte border)
        Creates a button with the given image and border. The transparentColor property of the Image must be set before calling this constructor.

      • Button

        protected Button()

    • Method Detail

      • setText

        public void setText​(java.lang.String text)
        Sets the text that is displayed in the button.
        Specified by:
        setText in interface TextControl

      • setImage

        public void setImage​(Image img)
        Sets the image that is displayed in the button. The transparentColor property of the Image must be set before calling this method.
        Note: this method does not resize the button to fit the image.

      • setPressedColor

        public void setPressedColor​(int newColor)
        Sets the color that the button's background will go ('armed color') when the button gets a PENDOWN event. The default is the cursor color for the background. In Android user interface style, using a bright color may result in a white background. Use a darker color in this case.
        Parameters:
        newColor - New color to set as the background when pressed.
        Since:
        SuperWaba 4.21

      • getText

        public java.lang.String getText()
        Gets the text displayed in the button.
        Specified by:
        getText in interface TextControl

      • getPreferredWidth

        public int getPreferredWidth()
        Returns the preffered width of this control.
        Overrides:
        getPreferredWidth in class Control

      • getPreferredHeight

        public int getPreferredHeight()
        Returns the preffered height of this control.
        Overrides:
        getPreferredHeight in class Control

      • simulatePress

        public void simulatePress()
        Press and depress this Button to simulate that the user had clicked on it. Does not generate events. If isSticky is true, inverts the button state.
        Since:
        SuperWaba 5.5
        See Also:
        isSticky

      • isPressed

        public boolean isPressed()
        Returns true if the button is pressed or not. Only makes sense if isSticky is true. You can change the button state programatically using simulatePress.
        Since:
        TotalCross 1.25
        See Also:
        simulatePress(), isSticky

      • onEvent

        public void onEvent​(Event event)
        Called by the system to pass events to the button.
        Overrides:
        onEvent in class Control
        Parameters:
        event - the event to process
        See Also:
        Event, KeyEvent, PenEvent

      • press

        public void press​(boolean pressed)
        Simulate the press or release of this button. Does not generate events.

      • setNinePatch

        public void setNinePatch​(Image img,
                         int corner,
                         int side)
        Description copied from class: Control
        Set the NinePatch of the control. This is used to draw the background image.
        Overrides:
        setNinePatch in class Control
        Parameters:
        img - The image to make the NinePatch. The image must be on a NinePatch format.
        corner - The size, in pixels, of the NinePatch's corner
        side - The size, in pixels, of the NinePatch's side.

      • setNinePatch

        public void setNinePatch​(Image img)
        Description copied from class: Control
        Set the NinePatch of the control. This is used to draw the background image.
        Overrides:
        setNinePatch in class Control
        Parameters:
        img - The image with guides to make the NinePatch. The image must be on a NinePatch format.

      • onPaint

        public void onPaint​(Graphics g)
        Called by the system to draw the button. it cuts the text if the button is too small.
        Overrides:
        onPaint in class Control
        Parameters:
        g - the graphics object for drawing
        See Also:
        Graphics

      • onFontChanged

        protected void onFontChanged()
        Description copied from class: Control
        Called after a setFont
        Overrides:
        onFontChanged in class Control

      • onBoundsChanged

        protected void onBoundsChanged​(boolean screenChanged)
        Description copied from class: Control
        Called after a setRect.
        Overrides:
        onBoundsChanged in class Control
        Parameters:
        screenChanged - If the bounds were changed due to a screen change (rotation, collapse)

      • onColorsChanged

        protected void onColorsChanged​(boolean colorsChanged)
        Description copied from class: Control
        Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container. If colorsChanged is true, it was called from setForeColor/setBackColor/Container.add; otherwise, it was called from setEnabled
        Overrides:
        onColorsChanged in class Control

      • paintBackground

        protected void paintBackground​(Graphics g)
        Paint button's background.

      • paintText

        protected void paintText​(Graphics g,
                         int tx,
                         int ty)
        Paint button's text.

      • paintImage

        protected void paintImage​(Graphics g,
                          boolean bkg,
                          int ix,
                          int iy)

      • getImage

        public Image getImage()
        Returns the image that is assigned to this Button, or null if none.