Concept : Understanding Adapters
Contents |
[edit] Description
Adapters in Bungee Connect, at their most basic level, are identifiers. (Connection adapters also act as interfaces.) At design time, you assign the same adapter to both a portion of the the View and a corresponding part of the Model. This facilitates loose coupling and dynamic, or late (runtime) binding between the View element and the Model element. In this way, at runtime, changes in that part of the View get propagated to the corresponding portion of the Model, and vice versa.
Note The DynamicForm control epitomizes this late binding. For an example of this behavior, import the DynamicForm sample code and explore the control's functionality.
[edit] Binding the View to the Model
In more concrete terms, you most often bind a control (part of your View) to a member of a class (part of your Model). To do this, you add an adapter at the project level of a solution. This is neccessary so that every adapter in your project is in the proper scope to be available for you to assign the adapter to any Model or View element in your project. You then use properties to assign that adapter to the appropriate portions of your Model and your View. The properties on the Adapter tab of the Property Editor are for assigning an adapter to a control (just select a control within the Design Editor, then select the Adapter tab on the Property Editor and use the appropriate property to assign the adapter to the control). Use the Adapter List property to assign the same adapter to the appropriate member of a class. At runtime this binding ensures that when a user changes something in the UI, the appropriate field in your Model updates, and vice-versa.
[edit] Using System Provided Adapters
Although you can create your own adapters, there are also many system provided adapters available in the Bungee Runtime. Using a system provided adapter provides the advantage of facilitating easy reuse and sharing of code, and also keeps your project from becoming too cluttered.
See the various adapter sections below for names and descriptions of some system provided adapters.
There are several types of adapters in Bungee Connect:
- Category Adapter
- Control Adapter
- Connection Adapter
- Event Adapter
- Form Adapter
- Function Adapter
- Property Adapter
- Sort Adapter
[edit] Category Adapter
A type of adapter that provides a way to declare whether or not an object contains usable properties. This property information is used by the Work Space object when you create an object. The Work Space object inspects the new object you create and, if you have set Category adapters, makes the properties available for editing at design time.
[edit] Control Adapter
A type of adapter that is added implicitly when you connect a control to an object, a control adapter binds the View element to the Model (object) so that changes in one propagate naturally to the other.
[edit] Connection Adapter
A conection adapter is a type of adapter which not only acts as an identifier, but also contains code acting as a generic interface to the specific functionality of a given data type. In the context of system provided adapters, this generic interface is most often to the behavior of a specific control. Each connection adapter requires a connection to implement the connection adapter's interface. Because of this extra functionality, when you add a connection adapter, you must choose a class for which the adapter can provide a generic interface, so that when you later add a connection, that connection can implement the interface provided through the adapter.
In the example below, the MyConnectionAdapter being created would provide an interface to the GoogleMap control. In order to be fully functional however, the developer creating this connection would also need to add a connection. The connection needed to impement the MyConnectionAdapter interface to the GoogleMap control would be a GoogleMapConnection.
[edit] System Provided Connection Adapters
Although there are system provided connection adapters, there is no wizard yet that easily displays them for you to choose. However, in adding a connection adapter, you can access a host of system classes for which your adapter can act as an interface. The most common scenario would be to choose a class from the TypeLib: ControlConnection project on the Dependencies tab of the Chooser, as these provide interfaces to each of the Bungee system controls (see the image above).
[edit] Event Adapter
A type of adapter used to bind any events an object may throw, for use by a second object.
[edit] Form Adapter
Form adapters provide a way to identify a form so that either the DynamicForm control or FormList control can locate and display that form at runtime. Typically, you add a form adapter to your project at the same time as you add a form to your class. The form adapter you add gets implemented at the project level .
After you add the form adapter to your project, you assign a form adapter to a form using the Adapter List property. You must also specify the same form adapter for the control in which you want the form to appear. You do this using an appropriate control property such as the DynamicForm control's Dynamic property, so the control can identify the correct form to display.
[edit] System Provided Form Adapters
System provided form adapters appear in the Runtime.FormAdapter tab of the Add Form wizard, as well as other wizards. The advantage of using these provided adapters is to facilitate reuse and sharing of code based on standardization of adapter names. Since adapters function primarily as identifiers, you can use any of the adapters below to identify any form you create. The names of the adapters are just aids to your memory as you construct your application.
| Name | Notes |
|---|---|
| Admin | |
| AppsManagerMainFormAdapter | Identifies the form you want to display as your main form. |
| Balloon | |
| ButtonBar | |
| CheckBox | |
| Contracted | |
| CordIconAdapter | |
| CordPageAdapter | |
| DataSourceDesign | Used in Datasource design |
| Default | Identifies a default form |
| Design | |
| Detail | Identifies the form to be used for the Detail in the Navigation, Summary and Detail paradigm (such as is used in popular e-mail programs) |
| Edit | |
| Expanded | |
| HTMLFormAdapter | Used to identify HTML cord |
| Large | |
| ListElement | Identifies form to be displayed in any list control |
| MCLDetail | |
| MCLEdit | |
| MCLReadOnly | |
| Row | |
| RowDetail | |
| Shell | |
| Sliver | |
| Small | |
| SubMenu | |
| Summary | Identifies the form to be used for the Summary in the Navigation, Summary and Detail paradigm (such as is used in popular e-mail programs) |
| TabFormAdapter | Identifies form to display in TabList Control |
| Test | Identifies a form for unit testing |
| Thumbnail | |
| Toolbar |
[edit] Function Adapter
Function Adapters provide an interface for locating the right function to use for a given action, such as a double-click action or a drag-and-drop action. For example, in the case of a FormList control bound to a collection, you may want to execute a function when a user double-clicks an element in the collection. To accomplish this, you assign the OnDoubleClick function adapter to the FormList control using the Double Click property on the control, and then assign the same function adapter to a function (using the function's Adapter List property). At runtime, when a user double-clicks a particular element, the function you identified with the adapter gets invoked.
Likewise, you use the Drag Function property to assign a function adapter to a control. You can then create functions that implement that function adapter's function signature to specify an action to take when a user drags-and-drops an element from the control.
Important Each type of system-provided function adapter provides a set of arguments as part of the function signature. You must implement these arguments in your function in the same order as they appear in the function signature if you want your function to pass parameters properly. You can find the function signatures for system-provided function adapters in the property documentation for a particular function adapter.
Function adapters have an added benefit if you rename a function. Because the function gets invoked by being identified (using an integer) by the adapter you specified, you do not need to write code to account for the name change.
For more information on working with function adapters, see Using Function Adapters.
[edit] System Provided Function Adapters
System provided function adapters are listed in the Runtime.FunctionAdapter tab of the Choose FunctionAdapter dialog that appears when you assign a function adapter to a control (for example when you use the Double Click property on a FormList control). The advantage of using these provided adapters is to facilitate reuse and sharing of code based on standardization of adapter names. Since adapters function primarily as identifiers, you can use any of the adapters below to identify any form you create. The names of the adapters are just aids to your memory as you construct your application.
| Name | Notes |
|---|---|
| GooglePinNotifyFunction | |
| MainRunFunction | Identifies the main function to run your application |
| OnAppointmentEditAdapter | |
| OnAppointmentEditSelectAdapter | |
| OnAppointmentNewAdapter | |
| OnAppointmentRangeAdapter | |
| OnAppointmentRemoveAdapter | |
| OnAppointmentSelectAdapter | |
| OnAppointmentUpdateAdapter | |
| OnCanCloseAdapter | |
| OnClick | |
| OnCloseFunctionAdapter | |
| OnCopyAdapter | |
| OnCreateAdapter | |
| OnDoubleClick | |
| OnDragDrop | |
| OnEnterKeyFunctionAdapter | |
| OnExpandAndChangeFunctionAdapter | |
| OnGetAdapter | |
| OnImageExecuteAdapter | |
| OnInsertAdapter | |
| OnLinkSelect | |
| OnMailTo | |
| OnMultipleSelect | |
| OnRangeFunctionAdapter | |
| OnRemoved | |
| OnSetDatesFunctionAdapter | |
| OnSingleSelect | |
| OnSortAdapter | |
| OnToolTipListboxAdapter | |
| PinNotifyFunction |
[edit] Property Adapter
A property adapter is an adapter exposed as a property in the Bungee Builder.
[edit] Sort Adapter
Sort adapters are used for sorting data in a collection. If you set a field of a class to be a sorted collection, then you can specify a Sort adapter. The Sort adapter allows you to define the sort criteria to be used in order to sort an object in a collection. At runtime, the collection will ask each object it references for the adapter view as specified by the collection's field properties.
[edit] See Also
Adding an Adapter
Understanding Connections
Adding a Connection