org.vishia.gral.ifc

Interface GralWidget_ifc

All Superinterfaces:

GralWidgetBase_ifc

All Known Subinterfaces:

GralCurveView_ifc, GralPanel_ifc, GralTable_ifc<UserData>, GralTableLine_ifc<UserData>, GralTextBox_ifc, GralTextField_ifc, GralWindow_ifc

All Known Implementing Classes:

GralArea9Panel, GralButton, GralCanvasArea, GralCurveView, GralHorizontalSelector, GralHtmlBox, GralInfoBox, GralLabel, GralLed, GralPanelContent, GralScreen, GralSlider, GralSwitchButton, GralTable, GralTable.TableLineData, GralTextBox, GralTextField, GralValueBar, GralWidget, GralWindow

public interface GralWidget_ifc
extends GralWidgetBase_ifc

This is the basic interface for all widgets of the Graphic Adaption Layer (gral).
Strategy of changing the graphical content of a widget:
2013-09-30
The SWT graphical implementation prohibits changing the graphical appearance, for example setText(newText), in another thread. Other graphical implementations are not thread-safe. Often a graphic application runs in only one thread, so that isn't a problem. But applications with complex data gathering processes needs to run in several threads. It may be fine to set the widgets in that threads immediately, seen from the programmers perspective. For multithread usage see org.vishia.gral.base.GralGraphicThread.

The solution of setting any content in a Widget in any thread in Gral is:

• The thread invokes methods of this GralWidget_ifc or methods of an derived GralWidget such as GralTable, for example setText(CharSequence), setTextColor(GralColor) or org.vishia.gral.base.GralTable#setColorCurrLine(GralColor).
• That methods store the given data either in the common GralWidget.DynamicData GralWidget.dyda of the widget or in specific data of a GralWidget implementation.
• That method calls redraw(int, int) with a proper millisecond delay (usual 100). The graphic implementation widget is not touched in this time. Usual it is not necessary to show information in a faster time than 100 ms if it is not a high speed animated graphic. The delayed repaint request saves calculation time if more as one property is changed on the same widget.
• The delayed repaint request queues the instance GralWidget#repaintRequ (only private visible) of GralGraphicOrder in the central queue of requests using org.vishia.gral.base.GralGraphicThread#addDispatchOrder(org.vishia.gral.base.GralGraphicOrder). The org.vishia.gral.base.GralGraphicThread is known by GralWidgetBase.gralMng.
• If for example 20 widgets are changed in maybe 40 properties, that queue contains the 20 instances of GralGraphicOrder. Any of them may have a specific delay. The graphic thread organizes it in a proper kind of time.
• If a GralGraphicOrder is dequeued in the graphic thread, its method org.vishia.gral.base.GralGraphicOrder#executeOrder(boolean) is invoked. This method calls GralWidgImplAccess_ifc.redrawGthread() via the association GralWidget._wdgImpl.
• The rerepaintGthread() method is overridden in the implementation layer with the necessary statements to transfer the non-graphic data of this GralWidget especially stored in GralWidget.dyda to the special implementation widget method invocations such as org.eclipse.swt.widgets.Text#setText(String) which touches the graphic widget. Then a org.eclipse.swt.widgets.Control#update() and org.eclipse.swt.widgets.Control#redraw() is invoked to show the content.

It is a complex approach. But it is simple for usage. The user can change the content in any thread. The user does not need to organize a queue for the graphic thread by itself. The queue is a part of Gral.

Strategy to create widgets and positioning: see GralMngBuild_ifc.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	GralWidget_ifc.ActionChange
static class	GralWidget_ifc.ActionChangeWhen

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	sVersion Version, history and license.

Method Summary

Modifier and Type	Method and Description
GralWidget_ifc.ActionChange	getActionChange(GralWidget_ifc.ActionChangeWhen when)
GralColor	getBackColor(int ix) Gets the background color for the widget.
java.lang.String	getCmd() Any widget can have a command String, which can be quest for example in an action.
long	getContentIdent() Gets the content identification of the users data which are set with setContentIdent(long).
java.lang.Object	getContentInfo()
java.lang.Object	getData() Gets the application specific info.
java.lang.String	getDataPath()
java.lang.Object	getImplWidget() Returns the implementation widget or its Wrapper.
boolean	isChanged(boolean setUnchanged) Returns true if the content is changed from a user action on GUI.
boolean	isEditable() Query whether this widget is able to change from user handling.
boolean	isGraphicDisposed() Returns true if the graphic implementatin widget was initialized, and then it was disposed.
boolean	isNotEditableOrShouldInitialize() Query whether this field should be written from any initial or actual data.
void	redraw() repaint request.
void	redraw(int delay, int latest) Possible delayed repaint, can be called in any thread.
void	refreshFromVariable(VariableContainer_ifc container) Capability for any widget to update its content from its associated variables described in its sDataPath.
void	refreshFromVariable(VariableContainer_ifc container, long timeAtleast, GralColor colorRefreshed, GralColor colorOld) Capability of any widget for refreshFromVariable(VariableContainer_ifc) but additionally the widget is shown as "too old" if the time stored with the variable is old.
void	setBackColor(GralColor color, int ix) Sets the background color for the widget.
GralColor	setBackgroundColor(GralColor color) Deprecated. use setBackColor(GralColor, int)
void	setBoundsPixel(int x, int y, int dx, int dy) This operation is used if the pixel are calculated on gral level.
void	setCmd(java.lang.String cmd) Any widget can have a command String, which can be quest for example in an action.
long	setContentIdent(long ident) Sets a identification for the shown data.
void	setData(java.lang.Object data) Sets a application specific data.
void	setDataPath(java.lang.String sDataPath) Sets the data path.
void	setEditable(boolean editable) Sets whether it is able to edit the content of the text field or text box.
void	setFocus(int delay, int latest) Sets the focus to the widget. .
GralColor	setForegroundColor(GralColor color) Deprecated. use setLineColor(GralColor, int)
void	setHtmlHelp(java.lang.String url) Sets the html help url for this widget.
void	setLineColor(GralColor color, int ix) Sets the line color for the widget.
void	setText(java.lang.CharSequence text) Set the text of the widget.
void	setTextColor(GralColor color) Sets the text color for the widget.

Methods inherited from interface org.vishia.gral.ifc.GralWidgetBase_ifc

getFocusedWidget, getImplAccess, getName, gralMng, isInFocus, isVisible, pos, setFocus, setFocused, setFocusedWidget, setVisible

Field Detail

sVersion

static final java.lang.String sVersion

Version, history and license.

• 2023-01-20 removed setVisibleStateWidget()
• 2016-08-31 Hartmut new: isGraphicDisposed() especially used for GralWindow-dispose detection.
• 2016-07-20 Hartmut chg: instead setToPanel now #createImplWidget_Gthread(). It is a better name.
• 2015-10-11 Hartmut new: #createImplWidget_Gthread() without mng as parameter.
• 2015-09-12 Hartmut new: getData(), setData(Object) was existent as GralWidget.setContentInfo(Object), now explicit property of any widget.
• 2015-07-12 Hartmut new: setCmd(String) and getCmd() is present in GralWidget since 2010 but it was not accepted as core property. But it is a core property.
• 2013-03-13 Hartmut new getContentIdent(), setContentIdent(long)
• 2013-03-13 Hartmut new isNotEditableOrShouldInitialize() to support edit fields.
• 2012-08-21 The method setBackColor(GralColor, int), setLineColor(GralColor, int) and setTextColor(GralColor) are declared here. What methods are deprecated? I thing setBackgroundColor(GralColor).
• 2012-07-29 Hartmut chg: GralWidgetBase_ifc.setFocus() and setFocus(int, int) can be called in any thread yet.
• 2012-07-13 Hartmut new. #getWidgetMultiImplementations(). This method is not used in any widget yet, but it may be necessary for complex widgets.
• 2012-04-25 Hartmut new: refreshFromVariable(VariableContainer_ifc): Capability for any widget to update its content from its associated variables described in its sDataPath.
• 2012-03-31 Hartmut new: GralWidgetBase_ifc.isVisible()
• 2012-01-16 Hartmut new: Concept redraw(), can be invoked in any thread. With delay possible.
• 2011-06-00 Hartmut created

Copyright/Copyleft:
For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but doesn't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you intent to use this source without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

Method Detail

getDataPath

java.lang.String getDataPath()

setCmd

void setCmd(java.lang.String cmd)

Any widget can have a command String, which can be quest for example in an action. The widget can be identified by its getCmd() independent of its name which can be set on runtime with this method.

getCmd

java.lang.String getCmd()

Any widget can have a command String, which can be quest for example in an action. The widget can be identified by this method independent of its name. See setCmd(String).

setData

void setData(java.lang.Object data)

Sets a application specific data. It should help to present user data which are associated to this widget. This info can be set and changed anytime.

getData

java.lang.Object getData()

Gets the application specific info. See #setContentInfo(Object).

getActionChange

GralWidget_ifc.ActionChange getActionChange(GralWidget_ifc.ActionChangeWhen when)

setFocus

void setFocus(int delay,
              int latest)

Sets the focus to the widget. . It can be called in any thread. If it is called in the graphic thread, the repaint action is executed immediately in the thread. Elsewhere the graphic thread will be woken up.

Specified by:

setFocus in interface GralWidgetBase_ifc

Parameters:

delay -

latest -

isGraphicDisposed

boolean isGraphicDisposed()

Returns true if the graphic implementatin widget was initialized, and then it was disposed. It is able to use especially to detect whether a sub window is closed or if the primary window was closed, to finish any other (waiting) thread. It may be used on any disposed widget.

Returns:

true if the Widget was created and after them disposed again.

setEditable

void setEditable(boolean editable)

Sets whether it is able to edit the content of the text field or text box. If a content is not able to edit, it is a showing field or box. The user can't change the content. But the user can set the cursor, select any text and copy to the systems clipboard. If the content is able to edit, the change should be notified and the content should be gotten. To do that TODO

Parameters:

editable - true then the content is going to be able to change. False then the edit functionality is disabled.

isEditable

boolean isEditable()

Query whether this widget is able to change from user handling.

isNotEditableOrShouldInitialize

boolean isNotEditableOrShouldInitialize()

Query whether this field should be written from any initial or actual data.

setBackgroundColor

@Deprecated
GralColor setBackgroundColor(GralColor color)

Deprecated. use setBackColor(GralColor, int)

setForegroundColor

@Deprecated
GralColor setForegroundColor(GralColor color)

Deprecated. use setLineColor(GralColor, int)

setBackColor

void setBackColor(GralColor color,
                  int ix)

Sets the background color for the widget. It supports widgets with more as one background color by an index. The usage of the index is widget-specific. An index -1 should mean: All backgrounds. ix=0 means the first background.

Parameters:

color - Any color

ix - -1 for non-specific, 0 for the first color or if only one color is supported, 1, ... if the widget has more as one background.

getBackColor

GralColor getBackColor(int ix)

Gets the background color for the widget.

Parameters:

ix - 0 if only one color is supported, 1, ... if the widget has more as one background.

Returns:

color Any color

setLineColor

void setLineColor(GralColor color,
                  int ix)

Sets the line color for the widget.

Parameters:

color - Any color

ix - 0 if only one color is supported, 1, ... if the widget has more as one line.

setTextColor

void setTextColor(GralColor color)

Sets the text color for the widget.

Parameters:

color - Any color

setText

void setText(java.lang.CharSequence text)

Set the text of the widget. If the widget is a button, the standard button text is changed. If it is a window, its title is changed.

Concept of changing a widget from application:
Here the generally approach is described, appropriate for this method, but in the same kind for all methods to set something like setBackColor(GralColor, int) etc.

With the set methods the user stores the text, color etc. in graphic-independent attributes. Then the method redraw(int, int) is invoked with the standard delay of #redrawtDelay and #redrawDelayMax. With that the widget-specific private instance of #repaintRequ is added to the queue of requests in the GralGraphicThread#addTimeEntry(GralGraphicOrder). In the requested time that dispatch order is executed in the graphic thread. It calls GralWidgImplAccess_ifc.redrawGthread(). That method is implemented in the graphic implementation layer of the widget. It sets the appropriate values from the independent Gral attributes to the implementation specifics and invoke a redraw of the graphic layer.

If more as one attribute is changed one after another, only one instance of the GralGraphicOrder is queued. All changed attributes are stored in DynamicData#whatIsChanged and the GralWidgImplAccess_ifc.redrawGthread() quests all changes one after another. It means that a thread switch is invoked only one time per widget for more as one change.
See DynamicData. That composite part of a widget stores all standard dynamic data of a widget.

setHtmlHelp

void setHtmlHelp(java.lang.String url)

Sets the html help url for this widget. That information will be used if the widget is focused to control the help window output.

Parameters:

url - String given url, maybe a local file too with #internalLabel.

redraw

void redraw()

repaint request. It can be called in any thread. If it is called in the graphic thread, the repaint action is executed immediately in the thread. Elsewhere the graphic thread will be waken up in the standard repaint time (about 100 ms). If this routine is invoked more as one time before the standard repaint time expires and not in the graphic thread, then the repaint is executed only one time after the given delay with the last set data. See redraw(int, int)

redraw

void redraw(int delay,
            int latest)

Possible delayed repaint, can be called in any thread. If this method is re-called in the time where the delay is not elapsed then the delay will be set newly, the timer is winding up again. But the latest time on first call will be used.

Parameters:

delay - in milliseconds. If 0 or less 0, then it is executed immediately if the calling thread is the graphic thread.

latest - The latest draw time in milliseconds. If it is <= 0, then it is unused. Note that a new call of repaint removes an existing repaint order to the new given time. With the latest argument for this time the repaint is always executing independent of new calls.

setBoundsPixel

void setBoundsPixel(int x,
                    int y,
                    int dx,
                    int dy)

This operation is used if the pixel are calculated on gral level. Intrinsic this operation is not system-conform, instead use grid units here. TODO look where it is used.

Parameters:

x -

y -

dx -

dy -

setDataPath

void setDataPath(java.lang.String sDataPath)

Sets the data path. It is a String in application context. If variables are used, it is the path of one or more variables, see refreshFromVariable(VariableContainer_ifc).

Parameters:

sDataPath -

isChanged

boolean isChanged(boolean setUnchanged)

Returns true if the content is changed from a user action on GUI.

Parameters:

setUnchanged - If true then set to unchanged with this call.

Returns:

true if the content was changed since last setUnchanged.

setContentIdent

long setContentIdent(long ident)

Sets a identification for the shown data. A widget may not need to refresh if the contentIdent is not changed. A refresh of a widget's content may have side effects in user handling such as selection of text etc. See getContentIdent().

Parameters:

ident - any number which identifies the value of content.

Returns:

the last stored ident.

getContentIdent

long getContentIdent()

Gets the content identification of the users data which are set with setContentIdent(long).

getContentInfo

java.lang.Object getContentInfo()

getImplWidget

java.lang.Object getImplWidget()

Returns the implementation widget or its Wrapper. Need cast due to implementation level.

Returns:

null if implementation is not existing.

refreshFromVariable

void refreshFromVariable(VariableContainer_ifc container)

Capability for any widget to update its content from its associated variables described in its sDataPath.

Parameters:

container - The container is used only if the variable is not known by direct reference in the private GralWidget.variable or GralWidget.variables. If the variable(s) is/are not known, they are searched by there data path set by setDataPath(String). More as one variables are possible separated by "," in the setDataPath("variable1, variable2"). The variables are searched in the container calling VariableContainer_ifc#getVariable(String).

refreshFromVariable

void refreshFromVariable(VariableContainer_ifc container,
                         long timeAtleast,
                         GralColor colorRefreshed,
                         GralColor colorOld)

Capability of any widget for refreshFromVariable(VariableContainer_ifc) but additionally the widget is shown as "too old" if the time stored with the variable is old. This helps to show the state of fields for updating.

Parameters:

container -

timeAtleast - The absolute time stamp after them the variable should be gotten a new value. It may be for example some seconds before the current time.

colorRefreshed - show with this background color if refreshed

colorOld - show with this background color if not refresehed.