OpenJDK / openjfx / 8 / master / rt
view modules/designTime/src/main/java/com/sun/javafx/beans/design/package.html @ 5976:94331ac42150
RT-25869: Update copyright year in header of modified source code files to 2013
Reviewed-by: Mong Hang Vo
| author | kcr |
|---|---|
| date | Mon, 23 Dec 2013 13:46:39 -0800 |
| parents | bcd662ba5826 |
| children |
line wrap: on
line source
<!-- Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved. DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. This code is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 only, as published by the Free Software Foundation. Oracle designates this particular file as subject to the "Classpath" exception as provided by Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License version 2 for more details (a copy is included in the LICENSE file that accompanied this code). You should have received a copy of the GNU General Public License version 2 along with this work; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA or visit www.oracle.com if you need additional information or have any questions. --> <!DOCTYPE html> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head> <body> <p> These packages define API for working with JavaFX components at design-time, predominantly within a GUI builder IDE. The API is split into two parts: those APIs intended to be implemented by component authors, and those APIs intended to be implemented by the IDE. The strict separation between these different APIs is used to create an environment where third party component authors can contribute components which plug-and-play well into specification compliant design tools, while remaining rich and highly interactive. </p> <p> A "Component" is a visual or non-visual JavaBean which conforms either to the normal JavaBeans conventions or to the JavaFX bean conventions. Any given bean is either mutable (and has a default no-arg constructor with setter methods) or immutable (and has a constructor accepting all args). For cases of immutable beans, there should be a Builder following the standard JavaFX convention. A component can be annotated to provide meta data for properties, although such annotations are not presently defined. Meta data is defined in the TODO:TBD package. Both visual components (such as a Rectangle, Pane, or Button) and non visual components (such as a Service) can be designed and configured by the GUI builder. </p> <p> The DesignInfo is the starting place for the design tool wishing to work with a specific bean. The design tool has some method for registering new beans with the tool. When it does so, it looks for the associated DesignInfo's for the registered beans. It instantiates and gets all further information about the custom bean, including any relevant help information, icons, etc, from the DesignInfo. Likewise, when parsing an FXML file, when a new type of bean is encountered, the design tool will look for a DesignInfo on the classpath for the associated bean. </p> <p> The DesignInfo also exposes the BeanMetaData, PropertyMetaData, and EventMetaData defined for some JavaBean. These meta data classes can, in turn, be turned by the IDE into DesignProperty, DesignEvent, and DesignBean instances. The meta-data classes contain the relevant and necessary meta-data information about the bean, its properties, and its events such as the name, reflective access to the getter, setter, and property methods, wiring up listeners and handling events. It contains information about which category each property or event should be grouped under including whether a property or event is preferred, hidden, or expert. It also contains information about what the default value for a particular property is. </p> <p> The various DesignXXX classes (other than DesignInfo, such as DesignContext, DesignProject, DesignBean, DesignProperty, and DesignEvent) are representations of various constructs from the tool's perspective. The tool will create instances of these classes which proxy access to the raw DesignInfo, Property, meta-data, etc. These classes are passed to code under the control of the component author when various interaction scenarios occur such as editing a property or handling drag and drop or data binding. That is, the purpose of these APIs is to represent the tool to the component author, while the purpose of DesignInfo is to represent the component to the tool. </p> <p> In GUI builders, there are essentially two major activities: constructing the UI and hooking it up to business logic. Constructing the UI consists of establishing a containment hierarchy and performing layout. To establish the containment hierarchy, the user may either manipulate the Hierarchy Viewer (where each essential element in the hierarchy is represented in a tree) or in the WYSIWYG layout area. The same DesignBeans are represented in both places. As a DesignBean is dragged onto the tree or layout from the palette, or as a DesignBean is dragged from one place on the tree or layout to another, the tool needs to ask for and receive feedback as to relevant drop targets. When dragged over a layout container in a scene, it needs to be able to ask for the expected new size and position if the drop were to happen at that location, such that an image representing the DesignBean could be resized and positioned where it would end up being dropped. </p> <p> Even non-visual components might have some visual representation in the tool. For example, a Service might be represented in some visual manner with simplified means for configuring the service. It might allow you to drag and drop onto it. At some point, data binding will be enabled and we will allow sources to be dragged or in some other way enable a binding mode so you can see all the binding interconnections. </p> <p> In the final design, it is expected that nearly all configuration for a component will be done by using annotations to describe the meta-data for a component. For example, an @Bean annotation would be used with a class to give it a different "displayName" or "category". The @Property annotation could be used to give a Property a reference to a different editor. Layout panes can be configured with meta data indicating what LayoutEditor should be used to provide information to the layout tool. </p> <p> However, since adding a runtime annotation to the classes will expose, via reflection, non-public API, we would like to avoid using the annotations until they become proper publicly supported API. As such, we are likely to hand-edit our DesignInfo classes and various meta data classes. Luckily, these use reflection to produce the bulk of their values. </p> <p> The DesignInfo and various MetaData classes are immutable. As such, we will introduce Builders to enable the construction of the MetaData, such that you can augment the reflection-supplied values as opposed to having to hand-write everything. There is not yet any provision for doing this, and to be honest it might make more sense to "leak" the annotations by making them runtime annotations, but we'll cross that bridge when we get there. </p> <p> </p> In the long term: - Annotations are provided such that the developer can add meta-data to JavaBeans, Properties, and Events. This meta-data includes things like names, data types, descriptions, etc. - If no DesignInfo is specified, an Introspector is capable of producing a DesignInfo. It uses reflection to look for properties and events on a JavaBean and generates the BeanMetaData, PropertyMetaData, and EventMetaData objects. If the JavaBean being inspected has annotations, those annotations are considered authoritative and used to create the meta-data. - If a DesignInfo is specified, then no automatic construction is done. However the Introspector can be used to generate the BeanMetaData, PropertyMetaData, and EventMetaData. This allows the hand-written DesignInfo to still get the benefit of automatically generated meta-data based on the annotations on the bean. Button: - Suppose I double click the button. In such a case, I want to see inline editing of the text. - Suppose I drag some node either from the palette, library, or from somewhere on the design canvas over the button. When I do, I would expect that a drop rectangle be shown over the button indicating the fact that it can accept that node as its graphic. Something needs to be done in the case that the Button has its graphic display property set to TEXT_ONLY or whatnot (perhaps stuff cannot be dropped onto it). - If I click on the button to drag it, and I click on the graphic, then what? What if the graphic is something complex like an inner scene? FlowPane: - When the FlowPane is selected I will want to show the padding between its children, as well as any insets etc around the FlowPane itself. hgap, vgap, rowVAlignment, columnHAlignment all are needed to display somehow on the pane, and perhaps be configurable on the pane. HBox: - fillHeight, spacing, alignment BorderPane: - Each position wants to be represented specially. Each should be drawn with dashed borders separating, and anything dropped in should somehow communicate how it fits within the space it has been given. So what is drawn is a combination of what properties are on the BorderPane itself, as well as what layout properties are defined on the children. </body> </html>