Package com.github.bordertech.wcomponents

Class WButton

    • Field Detail

      • NO_VALUE

        protected static final String NO_VALUE
        The default value to use when no value has been explicitly specified.
        See Also:
        Constant Field Values

    • Constructor Detail

      • WButton

        public WButton()
        Creates a WButton with no text or image. The button text must be set after construction.

      • WButton

        public WButton​(String text)
        Creates a WButton with the specified text.
        Parameters:
        text - the button text, using MessageFormat syntax. 
         // Will create a button with the text "Hello world"
 new WButton("Hello world");

      • WButton

        public WButton​(String text,
               char accessKey)
        Constructor. Set the button text and access key. Access keys are not case sensitive.
        Parameters:
        text - The button text.
        accessKey - The shortcut key that activates the button.

    • Method Detail

      • isDisabled

        public boolean isDisabled()
        Indicates whether this button is disabled in the given context.
        Specified by:
        isDisabled in interface Disableable
        Returns:
        true if this button is disabled, otherwise false.

      • setDisabled

        public void setDisabled​(boolean disabled)
        Sets whether this button is disabled when loaded. If your button is disabled by a WSubordinateControl then it is not necessary to explicitly set it has disabled.
        Specified by:
        setDisabled in interface Disableable
        Parameters:
        disabled - if true, this button is disabled. If false, it is enabled

      • handleRequest

        public void handleRequest​(Request request)
        Override handleRequest in order to perform processing for this component. This implementation checks whether the button has been pressed in the request.
        Specified by:
        handleRequest in interface WComponent
        Overrides:
        handleRequest in class AbstractWComponent
        Parameters:
        request - the request being responded to.

      • preparePaintComponent

        protected void preparePaintComponent​(Request request)
        Override preparePaintComponent to register an AJAX operation if this button is AJAX enabled.
        Overrides:
        preparePaintComponent in class AbstractWComponent
        Parameters:
        request - the request being responded to

      • clearPressed

        protected void clearPressed()
        Clear button is pressed flag.

      • isPressed

        public boolean isPressed()
        Indicates whether this button has been pressed for the current request.
        Returns:
        true if this button is pressed, false otherwise

      • setPressed

        protected void setPressed​(boolean pressed,
                          Request request)
        Sets whether this button is pressed. You probably do not want to invoke this manually, it is called from handleRequest(com.github.bordertech.wcomponents.Request). If the button is pressed its Action is queued so it is invoked after the entire request has been handled.
        Parameters:
        pressed - true for pressed, false for not pressed
        request - the Request that is being responded to

      • beforeActionExecute

        protected void beforeActionExecute​(Request request)
        Called before the button action is executed. Subclasses may override. Provides an opportunity to do preparation work before the action.execute
        Parameters:
        request - the request that is being responded to.

      • afterActionExecute

        protected void afterActionExecute​(Request request)
        Called after the button action has been executed. Subclasses may override. Provides an opportunity to do cleanup work after the action.execute.
        Parameters:
        request - the request that is being responded to.

      • focusMe

        protected void focusMe()
        Sets the focus back to this button unless explicity set elsewhere.

      • getAction

        public Action getAction()
        Returns:
        the action to execute when the button is pressed

      • setAction

        public void setAction​(Action action)
        Sets the action that you want run if the button is pressed.
        Parameters:
        action - the action to execute when the button is pressed 
         // Causes a message to be printed to the log whenever the button is pressed.
 setAction(new Action() {
   public void execute(final ActionEvent event) {
     LOG.info("The button was clicked at " + new Date());
   }
 });

      • getText

        public String getText()
        Return the button text. Returns:
        • user text if set; otherwise
        • shared text if set;
        • user value if set;
        • bean value if present; or
        • shared value.
        Returns:
        the button text

      • setText

        public void setText​(String text,
                    Serializable... args)
        Sets the button text. A button must have text even if it only displays an image. In this case the text is used to provide a text alternative to the image.
        Parameters:
        text - the button text, using MessageFormat syntax
        args - optional arguments for the button text format string 
         // Sets the button text to "Hello world"
 myButton.setText("Hello world");
 
         // Sets the button text to "Secret agent James Bond, 007"
 myButton.setText("Secret agent {0}, {1,number,000}", "James Bond", 7);

      • getValue

        public String getValue()
        Return the button value. By default the value is the same as the text placed on the button.
        Returns:
        the button value

      • setValue

        public void setValue​(String value)
        Set the button value.
        Parameters:
        value - the button value

      • getActionCommand

        public String getActionCommand()
        Same as getValue(). This method exists simply to clarify the relationship between the WButton, its Action, and the ActionEvent sent to the execute() method of the Action.
        Returns:
        the action command

      • setActionCommand

        public void setActionCommand​(String actionCommand)
        Same as setValue(). This method exists simply to clarify the relationship between the WButton, its Action, and the ActionEvent sent to the execute() method of the Action.
        Parameters:
        actionCommand - the action command

      • getActionObject

        public Object getActionObject()
        Returns the data object that has been associated with this button, else null. For convenience, this data object is passed to the execute() method of the button's associated Action, in the ActionEvent parameter.
        Returns:
        the action object

      • setActionObject

        public void setActionObject​(Serializable data)
        Associate this button with a data object that can be easily accessed in the execute() method of the button's associated Action.
        Parameters:
        data - the action object

      • getImage

        public Image getImage()
        Return the image to display on the button.
        Returns:
        the image

      • setImage

        public void setImage​(Image image)
        Sets the image to display on the button. The text alternative for the image is generated from the button text.
        Parameters:
        image - the image, or null for no image

      • setImage

        public void setImage​(String image)
        Sets the image to display on the button. The image will be read from the application's class path rather than from its web docs. The text alternative for the image is generated from the button text.
        Parameters:
        image - the relative path to the image resource, or null for no image

      • getImageHolder

        public WImage getImageHolder()
        Return the WImage used by this button to hold the Image resource.

        If the button is not using an Image resource, it will return null.

        Returns:
        the WImage holding the Image resource or null if the button is not using an Image resource

      • getImageUrl

        public String getImageUrl()
        Return the URL of the image to display on the button.
        Returns:
        the image url

      • setImageUrl

        public void setImageUrl​(String imageUrl)
        Sets the URL of the image to display on the button. This is the optimum way to set an image on a button as it allows the image to be served from a CDN and cached on the client for future use. In this way the same "image" may be used for many buttons (or other components) with no extra bandwidth use. The text alternative for the image is generated from the button text.
        Parameters:
        imageUrl - the image url, or null for no image

      • setImagePosition

        public void setImagePosition​(WButton.ImagePosition imagePosition)
        The position of the image on the button relative to the button text. If the button has an image and this is not set then the button text is used as the text alternative for the image and is not displayed on the button.
        Parameters:
        imagePosition - the position of the image

      • isRenderAsLink

        public boolean isRenderAsLink()
        Returns:
        true if this button should be rendered as a link.

      • setRenderAsLink

        public void setRenderAsLink​(boolean renderAsLink)
        Sets whether this button should be rendered like a link. This is a visual analog to a link, it does not cause the button to output a html 'a' element since the button still has to have a button element to accessibly undertake performance of any action which is not navigation. If you want to navigate with a link then you should be using WLink.
        Parameters:
        renderAsLink - true if this button should be rendered like a link.

      • isClientCommandOnly

        public boolean isClientCommandOnly()
        Returns:
        true if the button fires a client side command without causing a submit action. This is not necessarily incompatible with being an AjaxTrigger.

      • setClientCommandOnly

        public void setClientCommandOnly​(boolean client)
        Sets whether this button should fire a client command without submitting the form. What this actually does is indicates to the client that the button element is not a submit button so a form submit will not be triggered when the button is pressed. If the button is also an AjaxTrigger then the Ajax request will still fire unless the custom command specifically prevents this.

        If this is true then interacting with the button on the client will not submit the form. A custom command will fire if one is attached to the button through custom JavaScript.

        Parameters:
        client - indicates if the current button is to trigger a client action without a submit

      • isPopupTrigger

        public boolean isPopupTrigger()
        Indicates whether this button will trigger a WPopup when used.
        Returns:
        true if this button triggers a popup, false otherwise.

      • setPopupTrigger

        public void setPopupTrigger​(boolean popupTrigger)
        Sets whether this button will trigger a WPopup when used. This flag is used to provide information to the client on the button's intent. The actual invocation of the WPopup is done elsewhere, e.g. in the button's action.

        This must be set on every button which has a submit action or causes an ajax action if the resulting payload contains a WPopup. This is mandatory to meet accessibility guidelines as it is the only way the UI can forewarn assistive technologies that a button will cause a pop-up.

        Parameters:
        popupTrigger - The popupTrigger to set.

      • getAccessKey

        public char getAccessKey()
        Specified by:
        getAccessKey in interface AccessKeyable
        Returns:
        the component's access key.

      • setAccessKey

        public void setAccessKey​(char accessKey)
        Description copied from interface: AccessKeyable
        Set the access key on the component.
        Specified by:
        setAccessKey in interface AccessKeyable
        Parameters:
        accessKey - the key that will form a keyboard shortcut to the component.

      • isAjax

        public boolean isAjax()
        Indicates whether this button is AJAX enabled. A button is an AJAX button if it has a target set.
        Returns:
        true if this button is AJAX enabled, false otherwise

      • getAjaxTarget

        public AjaxTarget getAjaxTarget()
        Returns:
        the default AJAX target for this button

      • setAjaxTarget

        public void setAjaxTarget​(AjaxTarget ajaxTarget)
        Sets the AJAX target for the button. If a target is supplied, a an AJAX request is made rather than a round-trip to the server. The AJAX response will only contain the (possibly updated) target element rather than the entire UI. If a button has to target more than one component a WAjaxControl should be used instead.
        Parameters:
        ajaxTarget - the AJAX target.

      • isUnsavedChanges

        public boolean isUnsavedChanges()
        Indicates whether there are unsaved changes in the given context.
        Returns:
        true if there are unsaved changes, false if not.

      • setUnsavedChanges

        public void setUnsavedChanges​(boolean hasUnsavedChanges)
        This feature exists to pass information to the client to inform it that the server side thinks there are unsaved changes. It is used when a particular view is part of a multi-page process and the steps are not saved individually. The warning is triggered by a button or menu item with cancel set true.
        Parameters:
        hasUnsavedChanges - true if there are unsaved changes, false if not.

      • getMessage

        public String getMessage()
        Returns:
        the confirmation message for the button.

      • setMessage

        public void setMessage​(String message,
                       Serializable... args)
        Sets the confirmation message for the button. If a button has a confirmation message then the user is asked to confirm each invocation of the button unless the button also has cancel set true in which case the confirmation is only required if either there are unsaved changes on the server or the user has changed the value of any control in the current view without saving.
        Parameters:
        message - the confirmation message to display, using MessageFormat syntax
        args - optional arguments for the message format string

      • isCancel

        public boolean isCancel()
        Returns:
        true if the button is a cancel control and will warn the user of unsaved changes, otherwise false

      • setCancel

        public void setCancel​(boolean cancel)
        Sets the button as a cancel button. A cancel button is the same as any other button but has the following characteristics:
        • it can trigger an unsaved changes warning; and
        • it will not invoke client side validation;

        The action applied to a cancel button is normally one to undo the current process and possibly navigate to an initial view. A cancel button could be used in contexts such as going backwards through a multi-step process; returning to a previous view without committing changes in the current view; or logging out of an application.

        Parameters:
        cancel - true if the button is a cancel control and will warn the user of unsaved changes, otherwise false

      • getChildCount

        public int getChildCount()
        Specified by:
        getChildCount in interface Container
        Returns:
        the number of child components currently contained within this component.

      • getChildAt

        public WComponent getChildAt​(int index)
        Retrieves a child component by its index.
        Specified by:
        getChildAt in interface Container
        Parameters:
        index - the index of the child component to be retrieved.
        Returns:
        the child component at the given index.

      • getIndexOfChild

        public int getIndexOfChild​(WComponent childComponent)
        Retrieves the index of the given child.
        Specified by:
        getIndexOfChild in interface Container
        Parameters:
        childComponent - the child component to retrieve the index for.
        Returns:
        the index of the given child component, or -1 if the component is not a child of this component.

      • getChildren

        public List<WComponent> getChildren()
        Description copied from interface: Container
        Retrieves a list of this Container's.
        Specified by:
        getChildren in interface Container
        Returns:
        an immutable list of this Container.

      • toString

        public String toString()
        Description copied from class: AbstractWComponent
        Creates a String representation of this component; usually for debugging purposes.
        Overrides:
        toString in class AbstractWComponent
        Returns:
        a String representation of this component for debugging purposes

      • getComponentModel

        protected WButton.ButtonModel getComponentModel()
        Returns the effective component model for this component. Subclass may override this method to narrow the return type to their specific model type.
        Overrides:
        getComponentModel in class WBeanComponent
        Returns:
        the effective component model

      • getOrCreateComponentModel

        protected WButton.ButtonModel getOrCreateComponentModel()
        Retrieves the model for this component so that it can be modified. If this method is called during request processing, and a session specific model does not yet exist, then a new model is created. Subclasses may override this method to narrow the return type to their specific model type.
        Overrides:
        getOrCreateComponentModel in class WBeanComponent
        Returns:
        the model for this component