com.pekinsoft.spi.ButtonProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ServiceProviders Show documentation
An API that allows for dynamic application features and loose coupling.
The newest version!
/*
 * Copyright (C) 2022 PekinSOFT Systems
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see .
 * 
 * *****************************************************************************
 *  Project    :   AppFramework
 *  Class      :   ButtonProvider.java
 *  Author     :   Sean Carrick
 *  Created    :   Dec 13, 2022
 *  Modified   :   Dec 13, 2022
 *  
 *  Purpose: See class JavaDoc for explanation
 *  
 *  Revision History:
 *  
 *  WHEN          BY                   REASON
 *  ------------  -------------------  -----------------------------------------
 *  Dec 13, 2022  Sean Carrick         Initial creation.
 * *****************************************************************************
 */

package com.pekinsoft.spi;

import javax.swing.JButton;

/**
 * The {@code ButtonProvider} interface allows for an {@code Application} developer to provide a 
 * {@link javax.swing.JButton toolbar button} for their application.
 * 
 * How this works is that the {@code org.jdesktop.application.Application Application}
 * instance uses {@link org.openide.util.Lookup Lookup} to find the first
 * implementation of the {@link com.pekinsoft.spi.ToolbarProvider ToolbarProvider}
 * interface. If the {@code Lookup} returns null, then no
 * {@code ToolbarProvider} was found, so no toolbar is added to the application.
 * 
 * In that instance, the {@code Application} will seek out {@link 
 * com.pekinsoft.spi.ButtonProvider ButtonProvider} implementations and build a
 * toolbar using those.
 * 
 * One {@code ToolbarProvider} or the other {@code ButtonProvider}s must be used
 * to have a toolbar within the application. If neither is used, then the 
 * application's main window will have no toolbar.
 *
 * @author Sean Carrick <sean at pekinsoft dot com>
 * 
 * @version 1.3
 * @since 1.0
 */
public interface ButtonProvider extends Comparable {
    
    /**
     * Retrieves the {@link javax.swing.JButton button} to be added to a {@link 
     * javax.swing.JToolBar toolbar}.
     * 
     * @return the {@code JButton} to be added
     */
    public JButton getButton();
    
    /**
     * Retrieves the {@link javax.swing.JButton button's} desired position on
     * the {@link javax.swing.JToolBar toolbar}.
     * 
     * @return the {@code JButton}'s desired position
     */
    public int getPosition();
    
    /**
     * Determines whether a {@link javax.swing.JSeparator separator} is to be
     * added to the {@link javax.swing.JToolBar toolbar} after the button is
     * added. Since most buttons will not require a separator after them, the
     * default implementation of this method returns {@code false}.
     * 
     * @return {@code true} to add a separator after the button on the toolbar
     */
    public default boolean separatorAfter() {
        return false;
    }
    
    /**
     * Determines whether a {@link javax.swing.JSeparator separator} is to be
     * added to the {@link javax.swing.JToolBar toolbar} before the button is
     * added. Since most buttons will not require a separator before them, the
     * default implementation of this method returns {@code false}.
     * 
     * @return {@code true} to add a separator before the button on the toolbar
     */
    public default boolean separatorBefore() {
        return false;
    }

    @Override
    public default int compareTo(ButtonProvider o) {
        return Integer.compare(getPosition(), o.getPosition());
    }
    
}