1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans.
5 *
6 * CosyBeans is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * CosyBeans is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with CosyBeans. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.gui.displayers;
21
22 import java.beans.PropertyVetoException;
23
24 /**
25 * <code>Displayer</code> interface describes GUI component, which is able to
26 * dispaly on screen single dynamic data source.
27 *
28 * <p>
29 * If displayer GUI commponent is editable, this means can receive input from
30 * the end user, then such displayer will want to send this value change to the
31 * datasource back. In this case the displayer must implement also
32 * <code>DataSource</code> interface and accept consumers of type
33 * <code>NonblockingNumberConsumer</code> at least or other
34 * <code>Nonblocking<TYPPE>Consumer</code>,
35 * <code>Synchronous<TYPPE>Consumer</code> and
36 * <code>Asynchronous<TYPPE>Consumer</code> consumers. Displayer then
37 * sends user data change request to this consumers.
38 * </p>
39 *
40 * @author <a href="mailto:igor.kriznar@cosylab.com">Igor Kriznar</a>
41 * @version $Id: Displayer.java,v 1.9 2008-04-22 12:31:02 jbobnar Exp $
42 *
43 * @since Nov 24, 2003.
44 */
45 public interface Displayer extends DataConsumer, CommonDisplayer {
46 /** Java Bean property name for DataSource property. */
47 public static final String DATA_SOURCE = "dataSource";
48
49 /**
50 * Characteristic name for editable displayer JavaBean property. Displayers
51 * which support value editing <b>MUST</b> implement also setter
52 * <code>setEditable(booelan)</code> and support this characteristic name.
53 *
54 * @see #isEditable()
55 */
56 public static final String C_EDITABLE = "editable";
57
58 /**
59 * <p>
60 * Returns <code>true</code> if this displayer can interact with user and
61 * fire value updates requested by user. If displayer is editable, mus
62 * implement <code>DataSource</code> interface.
63 * </p>
64 *
65 * <p>
66 * Displayers, which does not support value editing will return allways
67 * <code>false</code>. Displayers which support value editing <b>MUST</b>
68 * implement also setter <code>setEditable(booelan)</code>.
69 * </p>
70 *
71 * @return <code>true</code> if this displayer can receive value change
72 * requestes by user
73 */
74 public boolean isEditable();
75
76 /**
77 * Returns the title of this displayer. Title migth be used to identfy which
78 * particular remote entity this is displayed.
79 *
80 * @return the title of this displayer
81 */
82 public String getTitle();
83
84 /**
85 * Sets the title of this displayer. Title migth be used to identfy which
86 * particular remote entity this is displayed. Setting to <code>null</code>
87 * will hide title.
88 *
89 * @param title
90 * new title of this displayer, can be <code>null</code>
91 */
92 public void setTitle(String title);
93
94 /**
95 * Sets data source and registeres this displayer as data consumer. This is
96 * convenience method for integration with VCE development tools, you can
97 * connect displayers directly to data sources without using this method.
98 *
99 * @param dataSource
100 * new data source of this displayer
101 *
102 * @throws PropertyVetoException
103 * DOCUMENT ME!
104 */
105 public void setDataSource(DataSource dataSource)
106 throws PropertyVetoException;
107
108 /**
109 * Returns data source. This is convenience method for integration with VCE
110 * development tools. If <code>null</code> returned does not mean that
111 * this displayer is not connected to data source, it only means that
112 * <code>setDataSource()</code> method was not used.
113 *
114 * @return the data source for this displayer, if set by setter
115 */
116 public DataSource getDataSource();
117
118 /*
119 * Below is try how to support DnD in Displayer. Ike is not sure what
120 * to do with it at the moment.
121 */
122
123 /*
124 * Set the URI of the data source being displayed by this displayer. The
125 * URIs are resoved to data sources ({@link DataSource}) through the
126 * {@link DataSourceResolver} interface.
127 *
128 * @param uri
129 * The URI of the data source.
130 */
131 //public void setDataSourceURI(String uri);
132
133 /*
134 * Get the URI of the data source currently being displayed by this
135 * displayer.
136 *
137 * @return The URI of the data source.
138 */
139 //public String getDataSourceURI();
140
141 /*
142 * Set the settings of the displayer. The settings define how the displayer
143 * renders the values from a data source (e.g., minimum and maximum values,
144 * color-coding, etc.).
145 *
146 * @param settings
147 * Settings to apply to the displayer.
148 */
149 //public void setDisplayerSettings(DisplayerSettings settings);
150
151 /*
152 * Fill-in the settings currently applied to the displayer. Note that this
153 * method does not reset the {@link DisplayerSettings} object passed as the
154 * parameter, but just sets/overrides the settings already there.
155 *
156 * @param settings
157 * The settings object to fill-in. If <code>null</code>, a new
158 * {@link DisplayerSettings} object is created and returned.
159 * @return The settings object that was filled-in with this displayer's
160 * settings.
161 */
162 //public DisplayerSettings getDisplayerSettings(DisplayerSettings settings);
163 }
164
165 /* __oOo__ */