Differences

This shows you the differences between two versions of the page.

--- jvx:reference [2020/06/10 12:52]
cduncan [Creating custom components]
+++ jvx:reference [2020/06/10 13:15]
cduncan [What is it?]
@@ Line 238: / Line 238: @@
 Because UI component is an abstract component designed for exactly this usage, the example might not be the most exciting one, but it clearly illustrates the mechanic.
-===== Bolting on functionality =====
+===== Bolting on Functionality =====
-Also from from the [[#part_about_creating_custom_components|part about creating custom components]] we can reuse the ''%%PostfixedLabel%%'' as example:
+Also, from the [[#part_about_creating_custom_components|part about creating custom components]], we can reuse the ''%%PostfixedLabel%%'' as example:
 <code java>
@@ Line 251: / Line 251: @@
 };
 </code>
-Now ''%%testLabel%%'' will be using the ''%%PostfixedLabel%%'' internally, but with no indication to the user of the object that this is the case. This allows to extend the functionality of a component completely transparently, especially in combination with functions which do return an ''%%UIComponent%%'' and similar.
+Now ''%%testLabel%%'' will be using the ''%%PostfixedLabel%%'' internally but with no indication to the user of the object that this is the case. This allows us to extend the functionality of a component completely transparently, especially in combination with functions that return a ''%%UI component%%'' and similar.
-===== An important note about the component hierarchy =====
+===== An Important Note About the Component Hierarchy =====
 If we create a simple component extensions, like the ''%%BeepComponent%%'' above, it is important to note that there is one other layer of indirection in regards to the hierarchy on the technology layer. If we create a simple frame with the ''%%BeepComponent%%'' in it, one might expect the following hierarchy:
@@ Line 268: / Line 268: @@
                                         \-Button
 </code>
-With the BeepComponent added and its sub-components as its children. However, the actual hierarchy looks like this:
+with the BeepComponent added and its subcomponents as its children. However, the actual hierarchy looks like this:
 <code>
@@ Line 280: / Line 280: @@
                                     \-Button
 </code>
-That is because such extended components are not “passed” to the Technology, they do only exist on the UI layer because they do not have a Technology component which could be used. That is done by adding the ''%%UIComponent%%'' to the UI parent, but for adding the actual Technology component the set UIResource is used.
+That is because such extended components are not “passed” to the technology; they only exist on the UI layer because they do not have a Technology component which could be used. That is done by adding the ''%%UI component%%'' to the UI parent, but for adding the actual technology component the set UI resource is used.
-===== The special case of containers =====
+===== The Special Case of Containers =====
-Another special case are containers. For example we could create a panel which does display an overlay in certain situations and we will need to use that throughout the whole application.
+Another special case is containers. For example, we could create a panel that displays an overlay in certain situations, and we will need to use that throughout the whole application.
 {{:jvx:reference:uiresourcecontainer.png?nolink|UIResourceContainer Example}}
-That means we do not want to build it every time anew, so one option would be to use a factory method to “wrap” the content, something like this:
+That means we do not want to build it every time anew, so one option would be to use a factory method to “wrap” the content. Something like this:
 <code java>
@@ Line 333: / Line 333: @@
 }
 </code>
-Which is easy enough, but let’s say we’d like to add logic to that wrapper, at that point it becomes more complicated. We can’t use the same technique as for custom component from above, because in that case the “overlaying panel” would simply not be displayed. However, there is a similar mechanism for containers, setting the UIResourceContainer.
+Which is easy enough, but let’s say we’d like to add logic to that wrapper. At that point, it becomes more complicated. We can’t use the same technique as the custom component from above because, in that case, the “overlaying panel” would simply not be displayed. However, there is a similar mechanism for containers: setting the UI resource container.
-The UIResourceContainer is another special mechanism which works similar to setting the UIResource, but it works exactly the other way round. While setting the UIResource does “hide” components from the Technology which are there in UI layer, setting the UIResourceContainer does hide components from the UI layer while there are added in the Technology. A little bit complicated, here is our example again using this technique:
+The UI resource container is another special mechanism that works similar to setting the UI resource, but it works exactly the other way round. While setting the UI resource “hides” components from the technology in UI layer, setting the UI resource container hides components from the UI layer, while they are added in the technology. A little complicated, here is our example using this technique again:
 <code java>
@@ Line 363: / Line 363: @@
 }
 </code>
-What we’ve done is extend an UIPanel (line #1), setting it up and adding children and then we’ve declared one of its children as the UIResourceContainer (line #22). So all methods which are specific to IContainer (adding children, setting a layout, etc.) are now forwarding to the innerPanel and manipulating the contents of the OverlayedPanel directly is not directly available.
+What we’ve done is extend a  UI panel (line #1), setting it up and adding children, and then we’ve declared one of its children as the UI resource container (line #22). So all methods that are specific to UI container (adding children, setting a layout, etc.) are now forwarding to the inner panel and manipulating the contents of the overlaid panel directly.
 And here is how it is used:
@@ Line 387: / Line 387: @@
 parentContainer.add(panel, UIBorderLayout.CENTER);
 </code>
-Notice that we can use it is any other panel (line #5) and simply add it to the parent (line #18). For a user of the API it is transparent as to whether there are more components or not, this is also visible in the created component hierarchy:
+Notice that we can use it as any other panel (line #5) and simply add it to the parent (line #18). For a user of the API, it is transparent as to whether there are more components or not. This is also visible in the created component hierarchy:
 <code>
@@ Line 413: / Line 413: @@
 Because of the way the [[https://sourceforge.net/projects/jvx/|JVx]] framework is designed, it is easy to access all layers of the GUI framework and also facilitate the usage of these layers to create custom components and allow easy access to the wrapped components, no matter on what layer or of what kind they are.
-====== Launchers and Applications ======
+====== Launchers and applications ======
 Let’s talk about Launchers, and how they are used to start [[https://sourceforge.net/projects/jvx/|JVx]] applications.
@@ Line 426: / Line 426: @@
 Then, and only then, the [[https://sourceforge.net/projects/jvx/|JVx]] application can run. Depending on the implementation that is used, that can be as easily as instancing the factory (Swing, JavaFX), but can also mean that a servlet server has to start (Vaadin). Because we do not wish to encumber our applications with technology specific code, we have to entrust all this to an encapsulated entity, meaning the implementations of ''%%ILauncher%%'' and ''%%IApplication%%''.
-===== Following the chain =====
+===== Following the Chain =====
 The steps for getting an application to start are as follows:
-  * The first thing that must run is obviously the JVM, without it we won’t have much luck starting anything.
+  * The first thing that must run is, obviously, the JVM. Without it, we won’t have much luck starting anything!
-  * The launcher must be created and it must start the Technology.
+  * The launcher must be created, and it must start the technology.
-  * The launcher than creates the application which the user is seeing.
+  * The launcher then creates the application, which the user is seeing.
 {{:jvx:reference:launcher.png?nolink|First the JVM starts, then the ILauncher (the window) and finally the IApplication (the content).}}
-So we need two classes, the ''%%ILauncher%%'' implementation which knows how to start the Technology and the ''%%IApplication%%'' implementation. That we already knew, so let’s try to put this into code. For simplicity reasons (and because I don’t want to write a complete factory from scratch for this example) we will reuse the Swing implementation and write a new launcher and application for it.
+So we need two classes, the ''%%ILauncher%%'' implementation that knows how to start the technology and the ''%%IApplication%%'' implementation. That we already knew, so let’s try to put this into code. For simplicity reasons (and because I don’t want to write a complete factory from scratch for this example), we will reuse the Swing implementation and write a new launcher and application for it.
-===== Entry point =====
+===== Entry Point =====
-The ''%%Main%%'' class that we will use as example is very straightforward:
+The ''%%main%%'' class that we will use as example is very straightforward:
 <code java>
@@ Line 457: / Line 457: @@
 }
 </code>
-All we have to do there is start the launcher itself. As the comment suggests, there might be work required for a “real” application startup. For this example, it is all we need to do. Of course we could also directly embed this little function into the launcher implementation itself, to save us one class.
+All we have to do there is start the launcher itself. As the comment suggests, there might be work required for a “real” application startup. For this example, it is all we need to do. Of course, we could also directly embed this little function into the launcher implementation itself to save us one class.
-===== The launcher =====
+===== The Launcher =====
-The ''%%ILauncher%%'' implementation on the other hand contains quite some logic, but nothing not manageable:
+The ''%%ILauncher%%'' implementation, on the other hand, contains quite some logic but nothing not manageable:
 <code java>
@@ Line 540: / Line 540: @@
 }
 </code>
-In short, the launcher is kicking off the Swing thread by invoking the startup method on the main Swing thread. This startup method will instantiate the factory and then create the application. From there we only need to set it visible and then our application has started.
+In short, the launcher is kicking off the Swing thread by invoking the startup method on the main Swing thread. This startup method will instantiate the factory and then create the application. From there, we only need to set it to visible and then our application has started.
-The launcher extends from ''%%SwingFrame%%'', that is required because there hasn’t been a factory created yet which could be used by UI components to create themselves. If we’d try to use an UI component before creating/setting a factory, we would obviously see the constructor of the component fail with a ''%%NullPointerException%%''.
+The launcher extends from ''%%SwingFrame%%''. That is required because there hasn’t been a factory created yet that could be used by UI components to create themselves. If we’d try to use an UI component before creating/setting a factory, we would see the constructor of the component fail with a ''%%NullPointerException%%''.
-The method ''%%startup()%%'' is invoked on the main Swing thread, which also happens to be the main UI thread for [[https://sourceforge.net/projects/jvx/|JVx]] in this application. Once we are on the main UI thread we can create the application, add it and then set everything to visible.
+The method ''%%startup()%%'' is invoked on the main Swing thread, which also happens to be the main UI thread for [[https://sourceforge.net/projects/jvx/|JVx]] in this application. Once we are on the main UI thread, we can create the application, add it, and then set everything to visible.
-===== The application =====
+===== The Application =====
-The ''%%IApplication%%'' implementation is quite short, because we extend ''%%com.sibvisions.rad.application.Application%%'', an ''%%IApplication%%'' implementation created with UI components.
+The ''%%IApplication%%'' implementation is quite short because we extend ''%%com.sibvisions.rad.application.Application%%'', an ''%%IApplication%%'' implementation created with UI components.
 <code java>
@@ Line 572: / Line 572: @@
 }
 </code>
-Because the launcher has previously started the technology and created the factory we can from here on now use UI components, which means we are already independent of the underlying technology. So the ''%%IApplication%%'' implementation can already be used with different technologies and is completely independent.
+Because the launcher has previously started the technology and created the factory, we can now use UI components, which means we are already independent of the underlying technology. So, the ''%%IApplication%%'' implementation can already be used with different technologies and is completely independent.
-===== Notes on the launcher =====
+===== Notes on the Launcher =====
-As you might have noticed, in our example the launcher is a (window) frame, that makes sense for nearly every desktop GUI toolkit as they all depend upon a window as main method to display their applications. But the launcher could also be simpler, for example just a call to start the GUI thread. Or it could be something completely different, for example an incoming HTTP request.
+As you might have noticed, in our example the launcher is a (window) frame. That makes sense for nearly every desktop GUI toolkit as they all depend upon a window as main method to display their applications. But the launcher could also be simpler: for example, just a call to start the GUI thread. Or it could be something completely different: for example, an incoming HTTP request.
-Also don’t forget that the launcher is providing additional functionality to the application, like saving file handles, reading and writing the configuration and similar platform and toolkit dependent operations, see the [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/swing/src/com/sibvisions/rad/ui/swing/impl/SwingApplication.java|launcher for Swing for further details]].
+Also, don’t forget that the launcher is providing additional functionality to the application, like saving file handles, reading and writing the configuration, and similar platform and toolkit-dependent operations. See the [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/swing/src/com/sibvisions/rad/ui/swing/impl/SwingApplication.java|launcher for Swing for further details]].
 ===== Conclusion =====
@@ Line 590: / Line 590: @@
 ===== What is it? =====
-DataBooks are an active model, which allow you to directly query and manipulate the data. Contrary to many other systems [[https://sourceforge.net/projects/jvx/|JVx]] does not map the data into objects, but instead allows you to directly access it in a table like fashion, exposing columns, rows and values.
+DataBooks are an active model, which allow you to directly query and manipulate the data. Contrary to many other systems, [[https://sourceforge.net/projects/jvx/|JVx]] does not map the data into objects, but allows you to directly access it in a table-like fashion exposing columns, rows, and values.
-One could say that it is like a three dimensional array, with these dimensions:
+One could say that it is like a three dimensional array with these dimensions:
   * DataPages
@@ Line 598: / Line 598: @@
   * Columns/Values
-With DataPages containing DataRows, which itself contain the values and everything is referencing the RowDefinition, which outlines how a row looks like.
+with DataPages containing DataRows, which in turn contain the values and everything referencing the RowDefinition, which further outlines how a row looks like.
 {{:jvx:reference:databook.png?nolink|DataBook Architecture, the DataBook contains DataPages, which contain DataRows.}}