← Back to branch summary

~ubuntu-branches/debian/stretch/insubstantial/stretch

« back to all changes in this revision

Viewing changes to flamingo/src/main/java/org/pushingpixels/flamingo/api/ribbon/resize/RibbonBandResizePolicy.java

  • Committer: Package Import Robot
  • Author(s): Felix Natter
  • Date: 2016-01-18 20:58:45 UTC
  • Revision ID: package-import@ubuntu.com-20160118205845-crbmrkda61qsi5qa
Tags: upstream-7.3+dfsg2
Import upstream version 7.3+dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
flamingo/src/main/java/org/pushingpixels/flamingo/api/ribbon/resize/RibbonBandResizePolicy.java
 
1
/*
 
2
 * Copyright (c) 2005-2010 Flamingo Kirill Grouchnikov. All Rights Reserved.
 
3
 *
 
4
 * Redistribution and use in source and binary forms, with or without 
 
5
 * modification, are permitted provided that the following conditions are met:
 
6
 * 
 
7
 *  o Redistributions of source code must retain the above copyright notice, 
 
8
 *    this list of conditions and the following disclaimer. 
 
9
 *     
 
10
 *  o Redistributions in binary form must reproduce the above copyright notice, 
 
11
 *    this list of conditions and the following disclaimer in the documentation 
 
12
 *    and/or other materials provided with the distribution. 
 
13
 *     
 
14
 *  o Neither the name of Flamingo Kirill Grouchnikov nor the names of 
 
15
 *    its contributors may be used to endorse or promote products derived 
 
16
 *    from this software without specific prior written permission. 
 
17
 *     
 
18
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
 
19
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
 
20
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
 
21
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
 
22
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
 
23
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
 
24
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
 
25
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
 
26
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
 
27
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
 
28
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
 
29
 */
 
30
package org.pushingpixels.flamingo.api.ribbon.resize;
 
31
 
 
32
import org.pushingpixels.flamingo.api.common.AbstractCommandButton;
 
33
import org.pushingpixels.flamingo.api.common.CommandButtonDisplayState;
 
34
import org.pushingpixels.flamingo.api.ribbon.*;
 
35
import org.pushingpixels.flamingo.api.ribbon.resize.CoreRibbonResizePolicies.*;
 
36
 
 
37
/**
 
38
 * Defines the resize policies for the {@link JRibbonBand}s and
 
39
 * {@link JFlowRibbonBand}s.
 
40
 * 
 
41
 * <p>
 
42
 * The resize policy defines a single visual state of the given ribbon band. For
 
43
 * every control in the specific ribbon band (command button, gallery etc), the
 
44
 * resize policy defines what is its display state.
 
45
 * </p>
 
46
 * 
 
47
 * <p>
 
48
 * The resize policies are installed with
 
49
 * {@link AbstractRibbonBand#setResizePolicies(java.util.List)} API. The order
 
50
 * of the resize policies in this list is important. The first entry in the list
 
51
 * must be the most permissive policies that returns the largest value from its
 
52
 * {@link #getPreferredWidth(int, int)}. Each successive entry in the list must
 
53
 * return the value smaller than its predecessors. The last entry
 
54
 * <strong>must</strong> be {@link IconRibbonBandResizePolicy}.
 
55
 * </p>
 
56
 * 
 
57
 * <p>
 
58
 * As the ribbon horizontal size is changed (by the user resizing the
 
59
 * application window), the ribbon task resize sequencing policy set by
 
60
 * {@link RibbonTask#setResizeSequencingPolicy(RibbonBandResizeSequencingPolicy)}
 
61
 * determines the order of ribbon bands to shrink / expand. See more details in
 
62
 * the documentation of the {@link RibbonBandResizeSequencingPolicy}.
 
63
 * </p>
 
64
 * 
 
65
 * <p>
 
66
 * The {@link CoreRibbonResizePolicies} provides a number of built in resize
 
67
 * policies that respect the application element priorities passed to
 
68
 * {@link JRibbonBand#addCommandButton(org.pushingpixels.flamingo.api.common.AbstractCommandButton, org.pushingpixels.flamingo.api.ribbon.RibbonElementPriority)}
 
69
 * and
 
70
 * {@link JRibbonBand#addRibbonGallery(String, java.util.List, java.util.Map, int, int, org.pushingpixels.flamingo.api.ribbon.RibbonElementPriority)}
 
71
 * APIs. There are three types of built in resize policies:
 
72
 * </p>
 
73
 * 
 
74
 * <ul>
 
75
 * <li>Resize policies for the {@link JFlowRibbonBand}s. The {@link FlowTwoRows}
 
76
 * and {@link FlowThreeRows} allow placing the flow ribbon band content in two
 
77
 * and three rows respectively.</li>
 
78
 * <li>Resize policies for the {@link JRibbonBand}s. The
 
79
 * {@link BaseCoreRibbonBandResizePolicy} is the base class for these policies.
 
80
 * These policies respect the {@link RibbonElementPriority} associated on
 
81
 * command buttons and ribbon galleries in {@link #getPreferredWidth(int, int)}
 
82
 * and {@link #install(int, int)}. While {@link #install(int, int)} call on a
 
83
 * {@link JFlowRibbonBand} only changes the bounds of the flow components, this
 
84
 * call on a {@link JRibbonBand} can also change the display state of the
 
85
 * command buttons (with
 
86
 * {@link AbstractCommandButton#setDisplayState(org.pushingpixels.flamingo.api.common.CommandButtonDisplayState)}
 
87
 * ) and the number of visible buttons in the ribbon galleries.</li>
 
88
 * <li>The collapsed policy that replaces the entire content of the ribbon band
 
89
 * with a single popup button. This is done when there is not enough horizontal
 
90
 * space to show the content of the ribbon band under the most restrictive
 
91
 * resize policy. Activating the popup button will show the original content
 
92
 * under the most permissive resize policy in a popup. This policy is
 
93
 * implemented in the {@link IconRibbonBandResizePolicy}.</li>
 
94
 * </ul>
 
95
 * 
 
96
 * <p>
 
97
 * In addition to the specific resize policies, the
 
98
 * {@link CoreRibbonResizePolicies} provides three core resize policies lists
 
99
 * for {@link JRibbonBand}s:
 
100
 * </p>
 
101
 * 
 
102
 * <ul>
 
103
 * <li>{@link CoreRibbonResizePolicies#getCorePoliciesPermissive(JRibbonBand)}
 
104
 * returns a list that starts with a resize policy that shows all command
 
105
 * buttons in the {@link CommandButtonDisplayState#BIG} and ribbon galleries
 
106
 * with the largest number of visible buttons, fully utilizing the available
 
107
 * screen space.</li>
 
108
 * <li>{@link CoreRibbonResizePolicies#getCorePoliciesRestrictive(JRibbonBand)}
 
109
 * returns a list that starts with a resize policy that respects the associated
 
110
 * ribbon element priority set on the specific components.</li>
 
111
 * <li> {@link CoreRibbonResizePolicies#getCorePoliciesNone(JRibbonBand)} returns
 
112
 * a list that only has a <code>mirror</code> resize policy that respects the
 
113
 * associated ribbon element priority set on the specific components.</li>
 
114
 * </ul>
 
115
 * 
 
116
 * <p>
 
117
 * Note that as mentioned above, all the three lists above have the
 
118
 * <code>collapsed</code> policy as their last element.
 
119
 * </p>
 
120
 * 
 
121
 * <p>
 
122
 * In addition, the
 
123
 * {@link CoreRibbonResizePolicies#getCoreFlowPoliciesRestrictive(JFlowRibbonBand, int)}
 
124
 * returns a restrictive resize policy for {@link JFlowRibbonBand}s. The list
 
125
 * starts with the two-row policy, goes to the three-row policy and then finally
 
126
 * to the collapsed policy.
 
127
 * </p>
 
128
 * 
 
129
 * @author Kirill Grouchnikov
 
130
 */
 
131
public interface RibbonBandResizePolicy {
 
132
        /**
 
133
         * Returns the preferred width of the associated ribbon band under the
 
134
         * specified dimensions.
 
135
         * 
 
136
         * @param availableHeight
 
137
         *            The height available for the associated ribbon band.
 
138
         * @param gap
 
139
         *            The inter-component gap.
 
140
         * @return The preferred width of the associated ribbon band under the
 
141
         *         specified dimensions.
 
142
         */
 
143
        public int getPreferredWidth(int availableHeight, int gap);
 
144
 
 
145
        /**
 
146
         * Installs this resize policy on the associated ribbon band. For
 
147
         * {@link JFlowRibbonBand}s only changes the bounds of the flow components.
 
148
         * For {@link JRibbonBand}s can also change the display state of the command
 
149
         * buttons (with
 
150
         * {@link AbstractCommandButton#setDisplayState(org.pushingpixels.flamingo.api.common.CommandButtonDisplayState)}
 
151
         * ) and the number of visible buttons in the ribbon galleries. Note that
 
152
         * this method is for internal use only and should not be called by the
 
153
         * application code.
 
154
         * 
 
155
         * @param availableHeight
 
156
         *            The height available for the associated ribbon band.
 
157
         * @param gap
 
158
         *            The inter-component gap.
 
159
         */
 
160
        public void install(int availableHeight, int gap);
 
161
}