001package com.fs.starfarer.api.campaign;
002
003import java.awt.Color;
004import java.util.List;
005
006import com.fs.starfarer.api.impl.campaign.rulecmd.SetStoryOption.StoryOptionParams;
007import com.fs.starfarer.api.ui.TooltipMakerAPI;
008import com.fs.starfarer.api.ui.ValueDisplayMode;
009
010
011public interface OptionPanelAPI {
012        
013        public static interface OptionTooltipCreator {
014                void createTooltip(TooltipMakerAPI tooltip, boolean hadOtherText);
015        }
016        
017        
018        void setTooltipHighlights(Object data, String ... highlights);
019        void setTooltipHighlightColors(Object data, Color ... colors);
020        
021        void clearOptions();
022
023        /**
024         * Adds an additional selectable option to the dialog.
025         * Options are appended in the order that this method is called.
026         *
027         * It usually makes sense to call clearOptions() before adding options to ensure that
028         * options don't pile up.
029         *
030         * @param text will be displayed in the option list
031         * @param data can be anything. This is used to identify the option, i.e. other methods that modify options need you
032         *             to pass the exact same thing you pass here. People often times use Strings or enums as option data.
033         *             Alternatively, you can use objects that implement an interface with e.g. an execute-method, to make the
034         *             option data directly contain the logic that should be executed when the option is selected by the player.
035         *             The value passed here is available in the optionSelected method of {@link com.fs.starfarer.api.campaign.InteractionDialogPlugin}.
036         *             Cast the optionData parameter to the type you used here to evaluate it.
037         */
038        void addOption(String text, Object data);
039        void addOption(String text, Object data, String tooltip);
040        void addOption(String text, Object data, Color color, String tooltip);
041        
042        /**
043         * Sets an alternate shortcut that works in addition to the number key.
044         * @param data
045         * @param code constant from org.lwjgl.input.Keyboard
046         * @param ctrl whether Control needs to be down to trigger this shortcut.
047         * @param alt whether Alt needs to be down to trigger this shortcut.
048         * @param shift whether Shift needs to be down to trigger this shortcut.
049         * @param putLast ignored
050         */
051        void setShortcut(Object data, int code, boolean ctrl, boolean alt, boolean shift, boolean putLast);
052        
053        /**
054         * Only works for options, not selectors.
055         * @param data
056         * @param enabled
057         */
058        void setEnabled(Object data, boolean enabled);
059        
060        
061        void setTooltip(Object data, String tooltipText);
062        
063        /**
064         * A user-adjustable bar useful for picking a value from a range.
065         * @param text Text to show above the bar.
066         * @param data ID of the bar, used to get/set its state.
067         * @param color Bar color.
068         * @param width Width in pixels, including value label on the right.
069         * @param maxValueWidth Width of the value label on the right.
070         * @param minValue Minimum value (when bar is all the way to the left).
071         * @param maxValue Maximum value (bar all the way to the right).
072         * @param mode How to display the value - as a percentage, X/Y, etc.
073         * @param tooltip Tooltip text. Can be null.
074         */
075        void addSelector(String text, Object data, Color color,
076                                         float width, float maxValueWidth, float minValue, float maxValue,
077                                         ValueDisplayMode mode, String tooltip);
078        
079        boolean hasSelector(Object data);
080        
081        void setSelectorValue(Object data, float value);
082        
083        float getSelectorValue(Object data);
084        float getMinSelectorValue(Object data);
085        float getMaxSelectorValue(Object data);
086        boolean hasOptions();
087        
088        List getSavedOptionList();
089        void restoreSavedOptions(List list);
090        
091        void addOptionConfirmation(Object optionId, String text, String yes, String no);
092        boolean hasOption(Object data);
093
094        /**
095         * This is what you want to use to add a story point option to a dialog.
096         * Using this method will handle everything a story option needs (story point cost, confirmation, ...), though
097         * you will need to set the color of the option manually.
098         *
099         * The alternative to using this method is to use
100         * {@link com.fs.starfarer.api.impl.campaign.rulecmd.SetStoryOption}.
101         *
102         * <p>Example:
103         * <pre>
104         * <code>
105         *    // given an object of type OptionPanelAPI named options
106         *      options.addOption("My story option [1SP, 0% XP]", "myData (can be any type)", Misc.getStoryOptionColor(), "tooltip (can be null)");
107         *      options.addOptionConfirmation(
108         *              "myData (can be any type)",
109         *              new BaseStoryPointActionDelegate() {
110         *                      {@code @Override}
111         *                      public String getLogText(){ return "this appears in the log"; }
112         *                      {@code @Override}
113         *                      public int getRequiredStoryPoints(){ return 1; }
114         *                      {@code @Override}
115         *                      public float getBonusXPFraction(){ return 0f; } // a value between 0 and 1. 1 Means 100% bonus XP
116         *                      {@code @Override}
117         *                      public boolean withSPInfo(){ return true; }
118         *                      {@code @Override}
119         *                      public String getTitle(){ return "title to display in confirmation box"; }
120         *                      {@code @Override}
121         *                      public void createDescription(TooltipMakerAPI info){ info.addPara("description text in confirmation box", 1f); }
122         *              }
123         *      );
124         * </code>
125         * </pre>
126         *
127         * @param data must be the same thing you passed to addOption
128         * @param confirmDelegate an object implementing the StoryPointActionDelegate interface. cf. example
129         */
130        void addOptionConfirmation(Object data, StoryPointActionDelegate confirmDelegate);
131        void addOptionTooltipAppender(Object data, OptionTooltipCreator optionTooltipCreator);
132        void setOptionText(String text, Object data);
133        boolean hasOptionTooltipAppender(Object data);
134        boolean optionHasConfirmDelegate(Object data);
135        Object getOptionDataBeingConfirmed();
136        void removeOption(Object data);
137
138        /**
139         * Calling this will not do everything neccessary to turn an option into a story point option.
140         * Use addOptionConfirmation instead. I believe this method is only used to modify existing story options.
141         * This method needs additional documentation, as I am not 100% sure what its purpose is.
142         *
143         * @param data identifier for the option
144         * @param params
145         * @param delegate
146         */
147        void setStoryOptionParams(Object data, StoryOptionParams params, StoryPointActionDelegate delegate);
148}