Permalink
Browse files

more dartdoc comments...

  • Loading branch information...
1 parent d82eedd commit 1dbb6ebd0e00464f11c3ded972dd8f7898d5fac9 @prujohn prujohn committed Jan 20, 2012
@@ -27,7 +27,7 @@ class FrameworkObject extends LucaObject {
/// if it has one.
///
/// ### To set the container context of an element:
- /// stateBag\[CONTAINER_CONTEXT\] = \{propertyNameOfElementContainerContext\};
+ /// stateBag[CONTAINER_CONTEXT] = {propertyNameOfElementContainerContext};
static final String CONTAINER_CONTEXT = "CONTAINER_CONTEXT";
//allows container elements to subscribe/unsubscribe to attached property changes of children
@@ -35,13 +35,16 @@
*
* ### Lucaxml usage:
* <MyElement my="42"></MyElement>
+ *
+ * ## See Also
+ * * [AttachedFrameworkProperty]
*/
class FrameworkProperty extends FrameworkPropertyBase
{
/// Represents the stored value of the FrameworkProperty.
///
/// Generally, this should not be access directly, but through:
- /// getValue(\{propertyName\});
+ /// getValue({propertyName});
Dynamic value = null;
/// Represents the previous value assigned to the FrameworkProperty.
@@ -17,14 +17,32 @@
/**
-* Base class for framework property types. */
+* Base class for framework property types.
+*
+* ## See Also
+* * [FrameworkProperty]
+* * [AttachedFrameworkProperty]
+*/
class FrameworkPropertyBase extends LucaObject{
+ /// Holds a reference to the object that the property belongs to.
final sourceObject;
+ /// Holds a callback function that is invoked whenever the value
+ /// of a property changes.
final Function propertyChangedCallback;
+ /// Holds the friendly name of the property.
final String propertyName;
+ /// Fires when the property value changes.
final FrameworkEvent<PropertyChangingEventArgs> propertyChanging;
+ /// Holds a converter that is used to convert strings into the type
+ /// Required by the property.
IValueConverter stringToValueConverter;
+ /// Constructs a FrameworkPropertyBase and initializes it to the framework.
+ ///
+ /// ### Parameters
+ /// * [LucaObject] sourceObject - the object the property belongs to.
+ /// * [String] propertyName - the friendly public name for the property.
+ /// * [Function] propertyChangedCallback - called by the framework when the property value changes.
FrameworkPropertyBase(this.sourceObject, this.propertyName, this.propertyChangedCallback) :
propertyChanging = new FrameworkEvent<PropertyChangingEventArgs>(){}
@@ -1,5 +1,29 @@
+// Copyright (c) 2012, John Evans & LUCA Studios LLC
+//
+// http://www.lucastudios.com/contact
+// John: https://plus.google.com/u/0/115427174005651655317/about
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+* Represents an [Exception] object that is throwing during failed attempts
+* to resolve a property from a dot-notation string.
+*
+* See [LucaObject] resolveProperty() method.
+*/
class FrameworkPropertyResolutionException implements Exception
{
+ /// The description of the exception that occurred.
final String message;
const FrameworkPropertyResolutionException(String this.message);
@@ -16,7 +16,11 @@
// limitations under the License.
/**
-* Interface contract for classes registering as presentation format providers. */
+* Interface contract for classes registering as presentation format providers.
+*
+* ## See Also
+* * [LucaxmlPresentationProvider]
+*/
interface IPresentationFormatProvider extends Hashable{
//TODO MIME as identifier type instead?
@@ -17,9 +17,12 @@
/**
* Represents a contract for an object that converts value to another value (and back).
+*
* Bi-directional conversion not yet supported. */
interface IValueConverter {
+ /// Returns a converted value from a given [Dynamic] value and optional [Dynamic]
+ /// parameter.
Dynamic convert(Dynamic value, [Dynamic parameter]);
//TODO implement two-way conversion support
View
@@ -16,12 +16,17 @@
// limitations under the License.
/**
-* Represents a View definition for the Framework
-* (in the MVVM context of a "view") */
+* Represents a View definition for the framework.
+*
+* (in the MVVM context of a "view")
+*
+*/
interface IView default _ViewFactory {
+ /// Gets the visual root of the view.
FrameworkElement get rootVisual();
+ /// Constructs a view from a given [FrameworkElement].
IView(FrameworkElement element);
}
@@ -1,19 +1,27 @@
-// Copyright (c) 2012, John Evans & LUCA Studios LLC
-//
-// http://www.lucastudios.com/contact
-// John: https://plus.google.com/u/0/115427174005651655317/about
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/// Copyright (c) 2012, John Evans & LUCA Studios LLC
+///
+/// <http://www.lucastudios.com/contact>
+///
+/// John: <https://plus.google.com/u/0/115427174005651655317/about>
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+/// <http://www.apache.org/licenses/LICENSE-2.0>
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+/// ## Try LUCA UI Online
+/// <http://www.lucastudios.com/trylucaui>
+///
+/// ## Project Source Code Repository
+/// <https://github.com/LUCA-Studios-LLC/LUCA-UI-Framework-for-Dart>
+
#library('LUCAUI_Framework_Core');
View
@@ -27,17 +27,20 @@ class LucaObject extends HashableObject{
LucaObject():
_stateBag = new HashMap<String, Dynamic>(),
_bindings = new List<Binding>(),
- _frameworkProperties = new Set<FrameworkProperty>()
- {
-
- }
+ _frameworkProperties = new Set<FrameworkProperty>();
+ /// Factory method for creating derived LucaObjects.
LucaObject makeMe() => new LucaObject();
+ /// Gets the stateBag [HashMap<String, Dynamic>] for the object.
HashMap<String, Dynamic> get stateBag() => _stateBag;
+ /// Gets a boolean value indicating whether the given object
+ /// is a container or not.
bool get isContainer() => false;
-
+
+ /// Returns a boolean value indicting whether the object contains
+ /// a [FrameworkProperty] by the given friendly [propertyName].
bool hasProperty(String propertyName) => _frameworkProperties.some((FrameworkProperty p) => p.propertyName.toLowerCase() == propertyName.toLowerCase());
FrameworkProperty _getPropertyByName(String propertyName){
View
@@ -20,23 +20,28 @@
*/
class LucaSystem extends FrameworkObject {
static final String _defaultRootID = "#LucaUIHost";
- static _RootElement visualRoot;
static IView _currentRootView;
static bool initialized = false;
static Element _domRootElement;
static HashMap<AttachedFrameworkProperty, HashMap<FrameworkObject, Dynamic>> _attachedProperties;
- static bool unitTestEnabled = false; //flag used to accomodate unit testing scenarios
static Set<IPresentationFormatProvider> presentationProviders;
-
static HashMap<String, FrameworkResource> _resourceRegistry;
-
//poor man's reflection...
static HashMap<String, Dynamic> _objectRegistry;
+ /// The root container that all elements are children of.
+ static _RootElement visualRoot;
+
+ /// **deprecated**
+ static bool unitTestEnabled = false; //flag used to accomodate unit testing scenarios
+
+ /// Central registry of named [FrameworkObject] elements.
static HashMap<String, FrameworkObject> namedElements;
- // Bindable window width/height properties. Readonly so can only bind from, not to.
- static FrameworkProperty windowWidthProperty, windowHeightProperty;
+ /// Bindable window width/height properties. Readonly so can only bind from, not to.
+ static FrameworkProperty windowWidthProperty;
+ /// Bindable window width/height properties. Readonly so can only bind from, not to.
+ static FrameworkProperty windowHeightProperty;
//"Singleton?"
static LucaSystem _ref;
@@ -108,7 +113,13 @@ class LucaSystem extends FrameworkObject {
LucaSystem.initialized = true;
}
-
+ /// Performs a search of the element tree starting from the given [FrameworkElement]
+ /// and returns the first named Element matching the given name.
+ ///
+ /// ** Deprecated **
+ ///
+ /// ## Instead use:
+ /// LucaSystem.namedElements[elementName];
static FrameworkElement findByName(String name, FrameworkElement startingWith){
if (startingWith.name != null && startingWith.name == name) return startingWith;
@@ -174,6 +185,7 @@ class LucaSystem extends FrameworkObject {
}
+ /// Returns a resource that is registered with the given [resourceKey].
static FrameworkResource retrieveResource(String resourceKey){
String lowered = resourceKey.trim().toLowerCase();
@@ -190,21 +202,24 @@ class LucaSystem extends FrameworkObject {
}
}
+ /// Registers a resource to the framework.
static void registerResource(FrameworkResource object){
LucaSystem._resourceRegistry[object.key.trim().toLowerCase()] = object;
}
-
+ /// Registers a LucaObject to the framework. Useful for registering
+ /// extension elements.
static void registerElement(LucaObject object){
LucaSystem._objectRegistry[object._type.trim().toLowerCase()] = object;
}
- //returns the innerWidth of the window
+ /// Gets the innerWidth of the window
static int get windowWidth() => (_ref != null) ? getValue(LucaSystem.windowWidthProperty) : -1;
- //returns the innerHeight of the window
+ /// Gets the innerHeight of the window
static int get windowHeight() => (_ref != null) ? getValue(LucaSystem.windowHeightProperty) : -1;
-
+
+ /// Sets the given view as the root visual element.
static set rootView(IView view){
LucaSystem._currentRootView = view;
visualRoot.content = view.rootVisual;
@@ -216,10 +231,11 @@ class LucaSystem extends FrameworkObject {
}
+ /// Gets the currently assigned view.
static IView get rootView() => LucaSystem._currentRootView;
- /**
- * Wraps a FrameworkElement into an IView and sets it to LucaSystem.rootView */
+
+ /// Wraps a FrameworkElement into an [IView] and sets it as the root view.
static void renderRaw(FrameworkElement element){
rootView = new IView(element);
}
View
@@ -17,7 +17,10 @@
/**
* Defines an observable version of List<T> that fires an event whenever items are added/removed from the list.
-* Note that the insertRange() method is not supported in this sub class */
+* Note that the insertRange() method is not supported in this sub class.
+*
+* See [List<T>] for information about specific methods.
+*/
class ObservableList<T> extends ListFactory<T>{
final FrameworkEvent<ListChangedEventArgs<T>> listChanged;
@@ -22,9 +22,20 @@ class Hyperlink extends FrameworkElement
{
Dynamic _content;
- FrameworkProperty contentProperty, targetNameProperty, navigateToProperty, foregroundProperty,
- fontSizeProperty, fontFamilyProperty;
+ /// Represents the content of the hyperlink.
+ FrameworkProperty contentProperty;
+ /// Represents the html 'target' value of the hyperlink.
+ FrameworkProperty targetNameProperty;
+ /// Represents the url navigation target of the hyperlink.
+ FrameworkProperty navigateToProperty;
+ /// Represents the foreground [Color] of a textual hyperlink.
+ FrameworkProperty foregroundProperty;
+ /// Represents the font size of a textual hyperlink.
+ FrameworkProperty fontSizeProperty;
+ /// Represents the font family value of a textual hyperlink.
+ FrameworkProperty fontFamilyProperty;
+ /// Overridden [LucaObject] method.
FrameworkObject makeMe() => new Hyperlink();
Hyperlink()
@@ -36,22 +47,34 @@ class Hyperlink extends FrameworkElement
this._stateBag[FrameworkObject.CONTAINER_CONTEXT] = contentProperty;
}
+ /// Gets the [navigateToProperty] value.
String get navigateTo() => getValue(navigateToProperty);
+ /// Sets the [navigateToProperty] value.
set navigateTo(String value) => setValue(navigateToProperty, value);
+ /// Gets the [targetNameProperty] value.
String get targetName() => getValue(targetNameProperty);
+ /// Sets the [targetNameProperty] value.
set targetName(String value) => setValue(targetNameProperty, value);
-
+
+ /// Gets the [contentProperty] value.
Dynamic get content() => getValue(contentProperty);
+ /// Sets the [targetNameProperty] value.
set content(Dynamic value) => setValue(contentProperty, value);
+ /// Gets the [foregroundProperty] value.
set foreground(SolidColorBrush value) => setValue(foregroundProperty, value);
+ /// Sets the [foregroundProperty] value.
SolidColorBrush get foreground() => getValue(foregroundProperty);
-
+
+ /// Gets the [fontFamilyProperty] value.
set fontFamily(String value) => setValue(fontFamilyProperty, value);
+ /// Sets the [fontFamilyProperty] value.
String get fontFamily() => getValue(fontFamilyProperty);
+ /// Gets the [fontSizeProperty] value.
set fontSize(num value) => setValue(fontSizeProperty, value);
+ /// Sets the [fontSizeProperty] value.
num get fontSize() => getValue(fontSizeProperty);
void _initHyperlinkProperties(){
@@ -124,6 +147,7 @@ class Hyperlink extends FrameworkElement
});
}
+ /// Overridden [FrameworkObject] method.
void CreateElement()
{
_component = _Dom.createByTag("a");
Oops, something went wrong.

0 comments on commit 1dbb6eb

Please sign in to comment.