JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
TooltipShape.java
Go to the documentation of this file.
1/**
2 * Copyright 2023-2024 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.graph.ui;
29
30import com.jogamp.graph.curve.Region;
31import com.jogamp.graph.curve.opengl.GLRegion;
32import com.jogamp.graph.curve.opengl.RegionRenderer;
33import com.jogamp.graph.ui.layout.Alignment;
34import com.jogamp.graph.ui.layout.BoxLayout;
35import com.jogamp.graph.ui.layout.Padding;
36import com.jogamp.graph.ui.shapes.Rectangle;
37import com.jogamp.math.Vec2f;
38import com.jogamp.math.Vec4f;
39import com.jogamp.math.geom.AABBox;
40import com.jogamp.opengl.GL2ES2;
41import com.jogamp.opengl.GLProfile;
42import com.jogamp.opengl.util.texture.TextureSequence;
43
44import jogamp.graph.ui.TreeTool;
45
46/** A HUD {@link Shape} {@link Tooltip} for client {@link Shape}, see {@link Shape#setToolTip(Tooltip)}. */
47public class TooltipShape extends Tooltip {
48 /**
49 * Optional HUD tip {@link #destroy(TooltipShape, GL2ES2, RegionRenderer, Shape) destroy callback}
50 * for the user provided {@link Shape}, see {@link Tooltip#destroyTip(GL2ES2, RegionRenderer, Shape)}.
51 * <p>
52 * In case no callback is being set via {@link TooltipShape#TooltipShape(Vec2f, long, Shape, DestroyCallback)}
53 * {@link Tooltip#destroyTip(GL2ES2, RegionRenderer, Shape)} destroys the shape.
54 * Otherwise this callback gets invoked.
55 * </p>
56 * <p>
57 * In case user provided {@code tip} is reused within a DAG,
58 * the provided implementation shall do nothing, i.e. use {@link TooltipShape#NoOpDtor}.
59 * </p>
60 * @see TooltipShape#TooltipShape(Vec2f, long, Shape, DestroyCallback)
61 * @see TooltipShape#createTip(Scene, AABBox)
62 */
63 public static interface DestroyCallback {
64 /**
65 * The custom destroy method of {@link DestroyCallback}
66 * @param tts the {#link TooltipShape} instance
67 * @param gl current {@link GL2ES2}
68 * @param renderer used {@link RegionRenderer}
69 * @param tip the user provided {@link Shape} as passed via {@link TooltipShape#TooltipShape(Vec4f, Vec4f, float, Vec2f, long, int, Shape, DestroyCallback)}.
70 */
71 public void destroy(TooltipShape tts, final GL2ES2 gl, final RegionRenderer renderer, final Shape tip);
72 }
73 /** No operation {@link DestroyCallback}, e.g. for a user provide {@code tip} {@link Shape}, reused within a DAG. */
75 @Override
76 public void destroy(final TooltipShape tts, final GL2ES2 gl, final RegionRenderer renderer, final Shape tip) { }
77 };
78
79 /** Shape of this tooltip */
80 private final Shape clientShape;
81 private final Vec2f scale;
82 private final float borderThickness;
83 private final Padding padding;
84 private final DestroyCallback dtorCallback;
85
86 /**
87 * Ctor of {@link TooltipShape}.
88 * <p>
89 * The tip {@link Shape} including the user provided {@code clientShape} will be destroyed via {@link #destroyTip(GL2ES2, RegionRenderer, Shape)},
90 * since no {@link DestroyCallback} is being provided via {@link TooltipShape#TooltipShape(Vec2f, long, Shape, DestroyCallback)}.
91 * </p>
92 * @param scale HUD tip scale for the tip shape
93 * @param delayMS delay until HUD tip is visible after timer start (mouse moved)
94 * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
95 * @param clientShape user/client {@link Shape} to be presented in the HUD tip
96 */
97 public TooltipShape(final Vec2f scale, final long delayMS, final int renderModes, final Shape clientShape) {
98 this(null, null, 0, null, scale, delayMS, renderModes, clientShape, null);
99 }
100
101 /**
102 * Ctor of {@link TooltipShape}.
103 * <p>
104 * The tip {@link Shape} will be destroyed via provided {@link DestroyCallback} {@code dtor} if not {@code null},
105 * otherwise the default {@link Tooltip#destroyTip(GL2ES2, RegionRenderer, Shape)} gets called.
106 * </p>
107 * <p>
108 * In case {@link DestroyCallback} {@code dtor} is being used, the user {@code clientShape}
109 * is removed from internal layout shapes before they get destroyed and the single {@code clientShape}
110 * gets passed to {@link DestroyCallback#destroy(TooltipShape, GL2ES2, RegionRenderer, Shape)}.
111 * </p>
112 * <p>
113 * In case user provided {@code clientShape} is reused within a DAG,
114 * the provided implementation shall do nothing, i.e. use {@link TooltipShape#NoOpDtor}.
115 * </p>
116 * @param backColor optional background color
117 * @param borderColor optional border color
118 * @param borderThickness border thickness
119 * @param padding optional padding for the given {@code clientShape} for the internal wrapper group
120 * @param scale scale for the HUD tip
121 * @param delayMS delay until HUD tip is visible after timer start (mouse moved)
122 * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
123 * @param clientShape user/client {@link Shape} to be presented in the HUD tip
124 * @param dtor optional {@link DestroyCallback}
125 */
126 public TooltipShape(final Vec4f backColor, final Vec4f borderColor, final float borderThickness,
127 final Padding padding, final Vec2f scale,
128 final long delayMS, final int renderModes, final Shape clientShape, final DestroyCallback dtor) {
129 super(backColor, borderColor, delayMS, renderModes);
130 this.clientShape = clientShape;
131 this.scale = scale;
132 this.borderThickness = borderThickness;
133 this.padding = padding;
134 this.dtorCallback = dtor;
135 }
136
137 public Shape getClientShape() { return this.clientShape; }
138
139 @Override
140 public Shape createTip(final Scene scene, final AABBox toolMvBounds) {
141 final float zEps = scene.getZEpsilon(16);
142
143 final float w = toolMvBounds.getWidth()*scale.x();
144 final float h = toolMvBounds.getHeight()*scale.y();
145
146 // tipWrapper ensures user 'clientShape' won't get mutated (scale, move) for DAG
147 final Group tipWrapper = new Group("TTS.wrapper", null, null, clientShape);
148 if( null != padding ) {
149 tipWrapper.setPaddding(padding);
150 }
151 final Group tipGroup = new Group(new BoxLayout(w, h, Alignment.FillCenter));
152 tipGroup.addShape(new Rectangle(renderModes, 1*w/h, 1, 0).setColor(backColor)
153 .setBorder(borderThickness).setBorderColor(frontColor)
154 .setName("TTS.frame").move(0, 0, -zEps));
155 tipGroup.setName("TTS.group");
156 tipGroup.addShape(tipWrapper);
157 tipGroup.setInteractive(false);
158
159 final Vec2f pos = getTipMvPosition(scene, toolMvBounds, w, h);
160 tipGroup.moveTo(pos.x(), pos.y(), 100*zEps);
161 return tipGroup;
162 }
163
164 /**
165 * Removed the user provided client {@link Shape} from the {@link #createTip(Scene, AABBox) created} HUD {@code tipGroup},
166 * i.e. {@link TooltipShape}'s layout {@link Group}.
167 * <p>
168 * This allows the user to release its own passed tip back, e.g. before destruction.
169 * </p>
170 * @param tip created tip {@link Shape} via {@link #createTip(Scene, AABBox)}
171 * @return the user provided client {@link Shape}
172 * @see #createTip(Scene, AABBox)
173 */
174 public Shape removeTip(final Shape tip) {
175 final Shape cs = clientShape;
176 if( null != cs ) {
177 final Group tipGroup = (Group)tip;
178 final Group tipWrapper = (Group)tipGroup.getShapeByIdx(1);
179 if( null == tipWrapper.removeShape(cs) ) {
180 System.err.println("TooltipShape.destroyTip: Warning: ClientShape "+cs.getName()+" not contained in "+tipWrapper.getName()+"; Internal Group: ");
181 TreeTool.forAll(tipGroup, (final Shape s) -> {
182 System.err.println("- "+s.getName());
183 return false;
184 });
185 }
186 }
187 return cs;
188 }
189
190 @Override
191 public void destroyTip(final GL2ES2 gl, final RegionRenderer renderer, final Shape tip) {
192 if( null != dtorCallback ) {
193 final Shape cs = removeTip(tip);
194 tip.destroy(gl, renderer);
195 dtorCallback.destroy(this, gl, renderer, cs);
196 } else {
197 super.destroyTip(gl, renderer, tip);
198 }
199 }
200}
Group of Shapes, optionally utilizing a Group.Layout.
Definition: Group.java:61
Shape getShapeByIdx(final int id)
Definition: Group.java:670
void addShape(final Shape s)
Adds a Shape.
Definition: Group.java:225
Shape removeShape(final Shape s)
Removes given shape, w/o Shape#destroy(GL2ES2, RegionRenderer).
Definition: Group.java:253
GraphUI Scene.
Definition: Scene.java:102
static float getZEpsilon(final int zBits, final PMVMatrixSetup setup)
Default Z precision on 16-bit depth buffer using -1 z-position and DEFAULT_ZNEAR.
Definition: Scene.java:126
Generic Shape, potentially using a Graph via GraphShape or other means of representing content.
Definition: Shape.java:87
Shape setName(final String name)
Set a symbolic name for this shape for identification.
Definition: Shape.java:339
final String getName()
Return the optional symbolic name for this shape, defaults to noname.
Definition: Shape.java:341
final Shape setInteractive(final boolean v)
Set whether this shape is interactive in general, i.e.
Definition: Shape.java:1711
final Shape moveTo(final float tx, final float ty, final float tz)
Move to scaled position.
Definition: Shape.java:543
final Shape setPaddding(final Padding padding)
Sets the unscaled padding for this shape, which is included in unscaled getBounds() and also includes...
Definition: Shape.java:376
final void destroy(final GL2ES2 gl, final RegionRenderer renderer)
Destroys all data.
Definition: Shape.java:457
A HUD Shape Tooltip for client Shape, see Shape#setToolTip(Tooltip).
Shape removeTip(final Shape tip)
Removed the user provided client Shape from the created HUD tipGroup, i.e.
TooltipShape(final Vec4f backColor, final Vec4f borderColor, final float borderThickness, final Padding padding, final Vec2f scale, final long delayMS, final int renderModes, final Shape clientShape, final DestroyCallback dtor)
Ctor of TooltipShape.
Shape createTip(final Scene scene, final AABBox toolMvBounds)
Create a new HUD tip shape, usually called by Scene.
TooltipShape(final Vec2f scale, final long delayMS, final int renderModes, final Shape clientShape)
Ctor of TooltipShape.
static DestroyCallback NoOpDtor
No operation DestroyCallback, e.g.
void destroyTip(final GL2ES2 gl, final RegionRenderer renderer, final Shape tip)
Destroy a created HUD tip.
A HUD tooltip for Shape, see Shape#setToolTip(Tooltip).
Definition: Tooltip.java:44
Vec2f getTipMvPosition(final Scene scene, final PMVMatrix4f pmv, final float tipWidth, final float tipHeight)
Little helper for createTip(Scene, AABBox) returning the Mv position of the tip within Scene Mv space...
Definition: Tooltip.java:158
final int renderModes
Graph's Region render modes, see create(..).
Definition: Tooltip.java:58
Immutable layout alignment options, including Bit#Fill.
Definition: Alignment.java:35
static final Alignment FillCenter
Bit#Fill, Bit#CenterHoriz and Bit#CenterVert alignment constant.
Definition: Alignment.java:45
GraphUI Stack Group.Layout.
Definition: BoxLayout.java:53
GraphUI CSS property Padding, unscaled space belonging to the element and included in the element's s...
Definition: Padding.java:38
A GraphUI rectangle GraphShape.
Definition: Rectangle.java:47
2D Vector based upon two float components.
Definition: Vec2f.java:37
4D Vector based upon four float components.
Definition: Vec4f.java:37
Axis Aligned Bounding Box.
Definition: AABBox.java:54
final float getWidth()
Definition: AABBox.java:879
final float getHeight()
Definition: AABBox.java:883
Optional HUD tip destroy callback for the user provided Shape, see Tooltip#destroyTip(GL2ES2,...
void destroy(TooltipShape tts, final GL2ES2 gl, final RegionRenderer renderer, final Shape tip)
The custom destroy method of DestroyCallback.