com.pekinsoft.spi.MenuProvider 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    :   Application
 *  Class      :   MenuProvider.java
 *  Author     :   Sean Carrick
 *  Created    :   Dec 12, 2022
 *  Modified   :   Dec 12, 2022
 *  
 *  Purpose: See class JavaDoc for explanation
 *  
 *  Revision History:
 *  
 *  WHEN          BY                   REASON
 *  ------------  -------------------  -----------------------------------------
 *  Dec 12, 2022  Sean Carrick         Initial creation.
 * *****************************************************************************
 */

package com.pekinsoft.spi;

import javax.swing.JMenu;

/**
 * The {@code MenuProvider} interface provides a method of allowing {@code Application} developers building on the
 * {@code org.jdesktop.application.Application Application} API to provide the individual
 * menus that make up the application's menu bar.
 * 
 * The way this works is that the {@code Application} uses the {@link 
 * org.openide.util.Lookup Lookup} to locate an implementation of the {@link 
 * com.pekinsoft.spi.MenuBarProvider MenuBarProvider} first. If that returns
 * null, then it moves on to seeking out {@code MenuProvider}s with which to 
 * build the application's menu.
 * 
 * One {@code MenuBarProvider} or the other {@code MenuProvider}s must be used
 * to have a menu bar within the application. If neither is used, then the 
 * application's main window will have no menu bar.
 *
 * @author Sean Carrick <sean at pekinsoft dot com>
 * 
 * @version 1.3
 * @since 1.0
 */
public interface MenuProvider extends Comparable {
    
    /**
     * The {@link javax.swing.JMenu JMenu} this provider is providing to the 
     * application. The {@code JMenu} this method returns should be fully setup
     * and configured, including with all of its {@link javax.swing.JMenuItem
     * JMenuItems}.
     * 
     * However, an application developer *could* request that only empty
     * menus be provided so that the menu items can be dynamically retrieved and
     * added to the individual menus. This is a decision left to the developer
     * and no "right" or "wrong" way to use this interface is enforced.
     * 
     * @return the {@code JMenu}, typically fully setup and configured for use,
     * including menu items within it
     */
    public JMenu getMenu();
    
    /**
     * Retrieves the `JMenuItem`'s desired position on the menu bar. This
     * would typically involve lower position values being toward the left end
     * of the menu bar, with higher position values being toward the right end.
     * 
     * @return the desired menu bar position
     */
    public int getPosition();


    /**
     * Compares this {@code MenuProvider}'s desired position with another
     * {@code MenuProvider}'s desired position to allow for sorting lists
     * of {@code MenuProvider} instances. This will allow an application
     * developer to make sure that the menus are always installed into the
     * application's menu bar in the same order each time the application is
     * launched.
     * 
     * @param o the other {@code MenuProvider} to compare positions
     * @return -1 if this provider is before the other; 0 if both want the same
     * position in the menu bar; 1 if this provider should come after the other
     * one
     */
    @Override
    public default int compareTo(MenuProvider o) {
        return Integer.compare(getPosition(), o.getPosition());
    }
    
}