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
line wrap: on
line source
 Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.

 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 if you need additional information or have any
<!DOCTYPE html>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
            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.
            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
            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.
            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
            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.
            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.
            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.
            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.
            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.
            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.

        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.

            - 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

            - 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.
            - fillHeight, spacing, alignment
            - 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.