← 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/JRibbonBand.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/JRibbonBand.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;
 
31
 
 
32
import java.awt.event.ActionListener;
 
33
import java.util.*;
 
34
 
 
35
import javax.swing.SwingConstants;
 
36
 
 
37
import org.pushingpixels.flamingo.api.common.*;
 
38
import org.pushingpixels.flamingo.api.common.icon.ResizableIcon;
 
39
import org.pushingpixels.flamingo.api.common.popup.JCommandPopupMenu;
 
40
import org.pushingpixels.flamingo.api.ribbon.resize.CoreRibbonResizePolicies;
 
41
import org.pushingpixels.flamingo.internal.ui.ribbon.*;
 
42
 
 
43
/**
 
44
 * Ribbon band component. Can host three types of content:
 
45
 * 
 
46
 * <ul>
 
47
 * <li>Command buttons added with
 
48
 * {@link #addCommandButton(AbstractCommandButton, RibbonElementPriority)}.</li>
 
49
 * <li>Wrapped core / 3rd party components added with
 
50
 * {@link #addRibbonComponent(JRibbonComponent)} or
 
51
 * {@link #addRibbonComponent(JRibbonComponent, int)}.</li>
 
52
 * <li>Ribbon galleries added with
 
53
 * {@link #addRibbonGallery(String, List, Map, int, int, RibbonElementPriority)}
 
54
 * .</li>
 
55
 * </ul>
 
56
 * 
 
57
 * <p>
 
58
 * Command buttons are added with associated {@link RibbonElementPriority}. The
 
59
 * higher the priority, the longer the button "stays" in the
 
60
 * {@link CommandButtonDisplayState#BIG} or
 
61
 * {@link CommandButtonDisplayState#MEDIUM} state - depending on the available
 
62
 * resize policies.
 
63
 * </p>
 
64
 * 
 
65
 * <p>
 
66
 * Wrapped components can span one or multiple rows. Use the
 
67
 * {@link #addRibbonComponent(JRibbonComponent, int)} API to add a wrapped
 
68
 * component that spans more than one row.
 
69
 * </p>
 
70
 * 
 
71
 * <p>
 
72
 * Once a ribbon gallery is added with
 
73
 * {@link #addRibbonGallery(String, List, Map, int, int, RibbonElementPriority)}
 
74
 * , you can use the following APIs to configure the content and behavior of
 
75
 * that gallery:
 
76
 * </p>
 
77
 * 
 
78
 * <ul>
 
79
 * <li>{@link #addRibbonGalleryButtons(String, String, JCommandToggleButton...)}
 
80
 * </li>
 
81
 * <li>{@link #removeRibbonGalleryButtons(String, JCommandToggleButton...)}</li>
 
82
 * <li>{@link #setSelectedRibbonGalleryButton(String, JCommandToggleButton)}</li>
 
83
 * <li>{@link #setRibbonGalleryExpandKeyTip(String, String)}</li>
 
84
 * <li>
 
85
 * {@link #setRibbonGalleryPopupCallback(String, RibbonGalleryPopupCallback)}</li>
 
86
 * </ul>
 
87
 * 
 
88
 * <p>
 
89
 * A ribbon band can have multiple visual groups separated with vertical
 
90
 * separator lines. To start a new unnamed group use the {@link #startGroup()}
 
91
 * API. To start a new named group use the {@link #startGroup(String)} API.
 
92
 * Unnamed groups will have three rows of controls. Named groups will have two
 
93
 * rows of controls, with the top row showing the group title.
 
94
 * </p>
 
95
 * 
 
96
 * @author Kirill Grouchnikov
 
97
 */
 
98
public class JRibbonBand extends AbstractRibbonBand<JBandControlPanel> {
 
99
        /**
 
100
         * This callback allows application code to place additional menu entries in
 
101
         * the popup menu shown when the ribbon gallery expand button is clicked.
 
102
         * Application code should use
 
103
         * {@link JCommandPopupMenu#addMenuButton(JCommandMenuButton)} and
 
104
         * {@link JCommandPopupMenu#addMenuSeparator()} APIs on the passed menu
 
105
         * parameter.
 
106
         * 
 
107
         * @author Kirill Grouchnikov
 
108
         */
 
109
        public static interface RibbonGalleryPopupCallback {
 
110
                /**
 
111
                 * Called just before the popup menu is about to be shown.
 
112
                 * 
 
113
                 * @param menu
 
114
                 *            The popup menu that will be shown.
 
115
                 */
 
116
                public void popupToBeShown(JCommandPopupMenu menu);
 
117
        }
 
118
 
 
119
        /**
 
120
         * Big size with landscape orientation. Used for buttons in in-ribbon
 
121
         * galleries.
 
122
         */
 
123
        public static final CommandButtonDisplayState BIG_FIXED_LANDSCAPE = new CommandButtonDisplayState(
 
124
                        "Big Fixed Landscape", 32) {
 
125
                @Override
 
126
                public CommandButtonLayoutManager createLayoutManager(
 
127
                                AbstractCommandButton button) {
 
128
                        return new CommandButtonLayoutManagerBigFixedLandscape();
 
129
                }
 
130
        };
 
131
 
 
132
        /**
 
133
         * Big size with landscape orientation. Used for buttons in in-ribbon
 
134
         * galleries.
 
135
         */
 
136
        public static final CommandButtonDisplayState BIG_FIXED = new CommandButtonDisplayState(
 
137
                        "Big Fixed", 32) {
 
138
                @Override
 
139
                public CommandButtonLayoutManager createLayoutManager(
 
140
                                AbstractCommandButton button) {
 
141
                        return new CommandButtonLayoutManagerBigFixed();
 
142
                }
 
143
        };
 
144
 
 
145
        /**
 
146
         * Constructs a <code>JRibbonBand</code> specifying the title and the icon
 
147
         * when in the collapsed state.
 
148
         * <p>
 
149
         * This is equivalent to <code>JRibbonBand(title, icon, null)</code>.
 
150
         * 
 
151
         * @see #JRibbonBand(String, ResizableIcon, ActionListener)
 
152
         * @param title
 
153
         *            band title
 
154
         * @param icon
 
155
         *            the icon displayed when the band collapses
 
156
         */
 
157
        public JRibbonBand(String title, ResizableIcon icon) {
 
158
                this(title, icon, null);
 
159
        }
 
160
 
 
161
        /**
 
162
         * Constructs a <code>JRibbonBand</code> specifying the title, the icon when
 
163
         * in the collapsed state, and the action listener for when the band is
 
164
         * expanded.
 
165
         * 
 
166
         * @param title
 
167
         *            band title
 
168
         * @param icon
 
169
         *            the icon displayed when the band collapses
 
170
         * @param expandActionListener
 
171
         *            Expand action listener (can be <code>null</code>).
 
172
         */
 
173
        public JRibbonBand(String title, ResizableIcon icon,
 
174
                        ActionListener expandActionListener) {
 
175
                super(title, icon, expandActionListener, new JBandControlPanel());
 
176
                this.resizePolicies = Collections
 
177
                                .unmodifiableList(CoreRibbonResizePolicies
 
178
                                                .getCorePoliciesPermissive(this));
 
179
                updateUI();
 
180
        }
 
181
 
 
182
        /**
 
183
         * Adds the specified command button to <code>this</code> band.
 
184
         * 
 
185
         * @param commandButton
 
186
         *            the command button to add
 
187
         * @param priority
 
188
         *            priority of the button
 
189
         */
 
190
        public void addCommandButton(AbstractCommandButton commandButton,
 
191
                        RibbonElementPriority priority) {
 
192
                commandButton.setHorizontalAlignment(SwingConstants.LEFT);
 
193
                this.controlPanel.addCommandButton(commandButton, priority);
 
194
        }
 
195
 
 
196
        public void addRibbonGallery(String galleryName,
 
197
                        List<StringValuePair<List<JCommandToggleButton>>> buttons,
 
198
                        Map<RibbonElementPriority, Integer> preferredVisibleButtonCounts,
 
199
                        int preferredPopupMaxButtonColumns,
 
200
                        int preferredPopupMaxVisibleButtonRows,
 
201
                        RibbonElementPriority priority) {
 
202
                this.addRibbonGallery(galleryName, buttons,
 
203
                                preferredVisibleButtonCounts, preferredPopupMaxButtonColumns,
 
204
                                preferredPopupMaxVisibleButtonRows,
 
205
                                JRibbonBand.BIG_FIXED_LANDSCAPE, priority);
 
206
        }
 
207
 
 
208
        /**
 
209
         * Adds a new ribbon gallery to <code>this</code> band.
 
210
         * 
 
211
         * @param galleryName
 
212
         *            Gallery name.
 
213
         * @param buttons
 
214
         *            Button groups.
 
215
         * @param preferredVisibleButtonCounts
 
216
         *            Preferred count of visible buttons of the ribbon gallery under
 
217
         *            different states.
 
218
         * @param preferredPopupMaxButtonColumns
 
219
         *            Preferred maximum columns in the popup gallery associated with
 
220
         *            the ribbon gallery.
 
221
         * @param preferredPopupMaxVisibleButtonRows
 
222
         *            Preferred maximum visible rows in the popup gallery associated
 
223
         *            with the ribbon gallery.
 
224
         * @param priority
 
225
         *            The initial ribbon gallery priority.
 
226
         * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
 
227
         * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
 
228
         * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
 
229
         */
 
230
        public void addRibbonGallery(String galleryName,
 
231
                        List<StringValuePair<List<JCommandToggleButton>>> buttons,
 
232
                        Map<RibbonElementPriority, Integer> preferredVisibleButtonCounts,
 
233
                        int preferredPopupMaxButtonColumns,
 
234
                        int preferredPopupMaxVisibleButtonRows,
 
235
                        CommandButtonDisplayState ribbonButtonDisplayState,
 
236
                        RibbonElementPriority priority) {
 
237
                JRibbonGallery gallery = new JRibbonGallery();
 
238
                gallery.setButtonDisplayState(ribbonButtonDisplayState);
 
239
                gallery.setName(galleryName);
 
240
                for (Map.Entry<RibbonElementPriority, Integer> prefCountEntry : preferredVisibleButtonCounts
 
241
                                .entrySet()) {
 
242
                        gallery.setPreferredVisibleButtonCount(prefCountEntry.getKey(),
 
243
                                        prefCountEntry.getValue());
 
244
                }
 
245
                gallery.setGroupMapping(buttons);
 
246
                gallery.setPreferredPopupPanelDimension(preferredPopupMaxButtonColumns,
 
247
                                preferredPopupMaxVisibleButtonRows);
 
248
 
 
249
//              this.controlPanel.addRibbonGallery(gallery, priority);
 
250
                addRibbonGallery(gallery, priority);
 
251
        }
 
252
 
 
253
        /**
 
254
         * Adds the specified command toggle buttons to a button group in the
 
255
         * specified ribbon gallery.
 
256
         * 
 
257
         * @param galleryName
 
258
         *            Ribbon gallery name.
 
259
         * @param buttonGroupName
 
260
         *            Button group name.
 
261
         * @param buttons
 
262
         *            Buttons to add.
 
263
         * @see #addRibbonGallery(String, List, Map, int, int,
 
264
         *      RibbonElementPriority)
 
265
         * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
 
266
         * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
 
267
         */
 
268
        public void addRibbonGalleryButtons(String galleryName,
 
269
                        String buttonGroupName, JCommandToggleButton... buttons) {
 
270
                JRibbonGallery gallery = this.controlPanel
 
271
                                .getRibbonGallery(galleryName);
 
272
                if (gallery == null)
 
273
                        return;
 
274
                gallery.addRibbonGalleryButtons(buttonGroupName, buttons);
 
275
        }
 
276
 
 
277
        /**
 
278
         * Adds the <code>gallery</code> to the ribbon band with a priority of
 
279
         * {@link RibbonElementPriority#TOP}.
 
280
         * 
 
281
         * @param gallery
 
282
         *            the ribbon gallery
 
283
         */
 
284
        public void addRibbonGallery(JRibbonGallery gallery) {
 
285
                controlPanel.addRibbonGallery(gallery, RibbonElementPriority.TOP);
 
286
        }
 
287
 
 
288
        /**
 
289
         * Adds the <code>gallery</code> to the ribbon band with the specified
 
290
         * <code>priority</code>.
 
291
         * 
 
292
         * @param gallery
 
293
         *            the ribbon gallery
 
294
         * @param priority
 
295
         *            the gallery priority
 
296
         */
 
297
        public void addRibbonGallery(JRibbonGallery gallery,
 
298
                        RibbonElementPriority priority) {
 
299
                controlPanel.addRibbonGallery(gallery, priority);
 
300
        }
 
301
 
 
302
        /**
 
303
         * Removes command toggle buttons from the specified ribbon gallery.
 
304
         * 
 
305
         * @param galleryName
 
306
         *            Ribbon gallery name.
 
307
         * @param buttons
 
308
         *            Buttons to remove.
 
309
         * @see #addRibbonGallery(String, List, Map, int, int,
 
310
         *      RibbonElementPriority)
 
311
         * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
 
312
         * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
 
313
         */
 
314
        public void removeRibbonGalleryButtons(String galleryName,
 
315
                        JCommandToggleButton... buttons) {
 
316
                JRibbonGallery gallery = this.controlPanel
 
317
                                .getRibbonGallery(galleryName);
 
318
                if (gallery == null)
 
319
                        return;
 
320
                gallery.removeRibbonGalleryButtons(buttons);
 
321
        }
 
322
 
 
323
        /**
 
324
         * Selects the specified command toggle button in the specified ribbon
 
325
         * gallery.
 
326
         * 
 
327
         * @param galleryName
 
328
         *            Ribbon gallery name.
 
329
         * @param buttonToSelect
 
330
         *            Button to select.
 
331
         * @see #addRibbonGallery(String, List, Map, int, int,
 
332
         *      RibbonElementPriority)
 
333
         * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
 
334
         * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
 
335
         */
 
336
        public void setSelectedRibbonGalleryButton(String galleryName,
 
337
                        JCommandToggleButton buttonToSelect) {
 
338
                JRibbonGallery gallery = this.controlPanel
 
339
                                .getRibbonGallery(galleryName);
 
340
                if (gallery == null)
 
341
                        return;
 
342
                gallery.setSelectedButton(buttonToSelect);
 
343
        }
 
344
 
 
345
        /**
 
346
         * Sets the display state for the buttons of the specified ribbon gallery.
 
347
         * 
 
348
         * @param galleryName
 
349
         *            Ribbon gallery name.
 
350
         * @param displayState
 
351
         *            Display state for the buttons of the matching ribbon gallery.
 
352
         */
 
353
        public void setRibbonGalleryButtonDisplayState(String galleryName,
 
354
                        CommandButtonDisplayState displayState) {
 
355
                JRibbonGallery gallery = this.controlPanel
 
356
                                .getRibbonGallery(galleryName);
 
357
                if (gallery == null)
 
358
                        return;
 
359
                gallery.setButtonDisplayState(displayState);
 
360
        }
 
361
 
 
362
        /**
 
363
         * Sets the application callback to place additional entries in the popup
 
364
         * menu shown when the specified ribbon gallery is expanded.
 
365
         * 
 
366
         * @param galleryName
 
367
         *            Gallery name.
 
368
         * @param popupCallback
 
369
         *            Application callback.
 
370
         * @see RibbonGalleryPopupCallback
 
371
         */
 
372
        public void setRibbonGalleryPopupCallback(String galleryName,
 
373
                        RibbonGalleryPopupCallback popupCallback) {
 
374
                JRibbonGallery gallery = this.controlPanel
 
375
                                .getRibbonGallery(galleryName);
 
376
                if (gallery == null)
 
377
                        return;
 
378
                gallery.setPopupCallback(popupCallback);
 
379
        }
 
380
 
 
381
        /**
 
382
         * Sets the key tip on the expand button of the specified ribbon gallery.
 
383
         * 
 
384
         * @param galleryName
 
385
         *            Gallery name.
 
386
         * @param expandKeyTip
 
387
         *            The key tip on the expand button of the specified ribbon
 
388
         *            gallery.
 
389
         */
 
390
        public void setRibbonGalleryExpandKeyTip(String galleryName,
 
391
                        String expandKeyTip) {
 
392
                JRibbonGallery gallery = this.controlPanel
 
393
                                .getRibbonGallery(galleryName);
 
394
                if (gallery == null)
 
395
                        return;
 
396
                gallery.setExpandKeyTip(expandKeyTip);
 
397
        }
 
398
 
 
399
        /**
 
400
         * Adds the specified ribbon component to this ribbon band.
 
401
         * 
 
402
         * @param comp
 
403
         *            The ribbon component to add.
 
404
         */
 
405
        public void addRibbonComponent(JRibbonComponent comp) {
 
406
                this.controlPanel.addRibbonComponent(comp);
 
407
        }
 
408
 
 
409
        /**
 
410
         * Adds the specified ribbon component to this ribbon band.
 
411
         * 
 
412
         * @param comp
 
413
         *            The ribbon component to add.
 
414
         * @param rowSpan
 
415
         *            Row span of the ribbon component.
 
416
         * @throws IllegalArgumentException
 
417
         *             if the row span is not legal. Legal row span is 1..3 for
 
418
         *             unnamed groups and 1..2 for named groups.
 
419
         * @see #startGroup()
 
420
         * @see #startGroup(String)
 
421
         */
 
422
        public void addRibbonComponent(JRibbonComponent comp, int rowSpan) {
 
423
                int groupCount = this.controlPanel.getControlPanelGroupCount();
 
424
                String groupTitle = (groupCount > 0) ? this.controlPanel
 
425
                                .getControlPanelGroupTitle(groupCount - 1) : null;
 
426
                int availableRows = (groupTitle == null) ? 3 : 2;
 
427
                if ((rowSpan <= 0) || (rowSpan > availableRows)) {
 
428
                        throw new IllegalArgumentException(
 
429
                                        "Row span value not supported. Should be in 1.."
 
430
                                                        + availableRows + " range");
 
431
                }
 
432
                this.controlPanel.addRibbonComponent(comp, rowSpan);
 
433
        }
 
434
 
 
435
        /**
 
436
         * Starts a new unnamed group.
 
437
         * 
 
438
         * @return The index of the new group.
 
439
         */
 
440
        public int startGroup() {
 
441
                return this.controlPanel.startGroup();
 
442
        }
 
443
 
 
444
        /**
 
445
         * Starts a new named group.
 
446
         * 
 
447
         * @param groupTitle
 
448
         *            The group title.
 
449
         * @return The index of the new group.
 
450
         */
 
451
        public int startGroup(String groupTitle) {
 
452
                return this.controlPanel.startGroup(groupTitle);
 
453
        }
 
454
 
 
455
        /**
 
456
         * Changes the title of the specified group.
 
457
         * 
 
458
         * @param groupIndex
 
459
         *            Group index.
 
460
         * @param groupTitle
 
461
         *            The new title for this group.
 
462
         */
 
463
        public void setGroupTitle(int groupIndex, String groupTitle) {
 
464
                this.controlPanel.setGroupTitle(groupIndex, groupTitle);
 
465
        }
 
466
 
 
467
        public List<JRibbonComponent> getRibbonComponents(int groupIndex) {
 
468
                return this.controlPanel.getRibbonComponents(groupIndex);
 
469
        }
 
470
 
 
471
        /*
 
472
         * (non-Javadoc)
 
473
         * 
 
474
         * @see org.jvnet.flamingo.ribbon.AbstractRibbonBand#cloneBand()
 
475
         */
 
476
        @Override
 
477
        public AbstractRibbonBand<JBandControlPanel> cloneBand() {
 
478
                AbstractRibbonBand<JBandControlPanel> result = new JRibbonBand(
 
479
                                this.getTitle(), this.getIcon(), this.getExpandActionListener());
 
480
                result.applyComponentOrientation(this.getComponentOrientation());
 
481
                return result;
 
482
        }
 
483
}