diff --git a/apidoc_config/Languages.txt b/apidoc_config/Languages.txt new file mode 100644 index 0000000000..aa9ce802fe --- /dev/null +++ b/apidoc_config/Languages.txt @@ -0,0 +1,113 @@ +Format: 1.35 + +# This is the Natural Docs languages file for this project. If you change +# anything here, it will apply to THIS PROJECT ONLY. If you'd like to change +# something for all your projects, edit the Languages.txt in Natural Docs' +# Config directory instead. + + +# You can prevent certain file extensions from being scanned like this: +# Ignore Extensions: [extension] [extension] ... + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Unlike other Natural Docs configuration files, in this file all comments +# MUST be alone on a line. Some languages deal with the # character, so you +# cannot put comments on the same line as content. +# +# Also, all lists are separated with spaces, not commas, again because some +# languages may need to use them. +# +# Language: [name] +# Alter Language: [name] +# Defines a new language or alters an existing one. Its name can use any +# characters. If any of the properties below have an add/replace form, you +# must use that when using Alter Language. +# +# The language Shebang Script is special. It's entry is only used for +# extensions, and files with those extensions have their shebang (#!) lines +# read to determine the real language of the file. Extensionless files are +# always treated this way. +# +# The language Text File is also special. It's treated as one big comment +# so you can put Natural Docs content in them without special symbols. Also, +# if you don't specify a package separator, ignored prefixes, or enum value +# behavior, it will copy those settings from the language that is used most +# in the source tree. +# +# Extensions: [extension] [extension] ... +# [Add/Replace] Extensions: [extension] [extension] ... +# Defines the file extensions of the language's source files. You can +# redefine extensions found in the main languages file. You can use * to +# mean any undefined extension. +# +# Shebang Strings: [string] [string] ... +# [Add/Replace] Shebang Strings: [string] [string] ... +# Defines a list of strings that can appear in the shebang (#!) line to +# designate that it's part of the language. You can redefine strings found +# in the main languages file. +# +# Ignore Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ... +# +# Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# Specifies prefixes that should be ignored when sorting symbols in an +# index. Can be specified in general or for a specific topic type. +# +#------------------------------------------------------------------------------ +# For basic language support only: +# +# Line Comments: [symbol] [symbol] ... +# Defines a space-separated list of symbols that are used for line comments, +# if any. +# +# Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ... +# Defines a space-separated list of symbol pairs that are used for block +# comments, if any. +# +# Package Separator: [symbol] +# Defines the default package separator symbol. The default is a dot. +# +# [Topic Type] Prototype Enders: [symbol] [symbol] ... +# When defined, Natural Docs will attempt to get a prototype from the code +# immediately following the topic type. It stops when it reaches one of +# these symbols. Use \n for line breaks. +# +# Line Extender: [symbol] +# Defines the symbol that allows a prototype to span multiple lines if +# normally a line break would end it. +# +# Enum Values: [global|under type|under parent] +# Defines how enum values are referenced. The default is global. +# global - Values are always global, referenced as 'value'. +# under type - Values are under the enum type, referenced as +# 'package.enum.value'. +# under parent - Values are under the enum's parent, referenced as +# 'package.value'. +# +# Perl Package: [perl package] +# Specifies the Perl package used to fine-tune the language behavior in ways +# too complex to do in this file. +# +#------------------------------------------------------------------------------ +# For full language support only: +# +# Full Language Support: [perl package] +# Specifies the Perl package that has the parsing routines necessary for full +# language support. +# +#------------------------------------------------------------------------------- + +# The following languages are defined in the main file, if you'd like to alter +# them: +# +# Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python, +# PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile, +# ActionScript, ColdFusion, R, Fortran + +# If you add a language that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# languages [at] naturaldocs [dot] org. diff --git a/apidoc_config/Menu.txt b/apidoc_config/Menu.txt new file mode 100644 index 0000000000..df42f638bd --- /dev/null +++ b/apidoc_config/Menu.txt @@ -0,0 +1,177 @@ +Format: 1.35 + + +Title: OpenLayers +SubTitle: JavaScript Mapping Library + +# You can add a footer to your documentation like this: +# Footer: [text] +# If you want to add a copyright notice, this would be the place to do it. + + +# -------------------------------------------------------------------------- +# +# Cut and paste the lines below to change the order in which your files +# appear on the menu. Don't worry about adding or removing files, Natural +# Docs will take care of that. +# +# You can further organize the menu by grouping the entries. Add a +# "Group: [name] {" line to start a group, and add a "}" to end it. +# +# You can add text and web links to the menu by adding "Text: [text]" and +# "Link: [name] ([URL])" lines, respectively. +# +# The formatting and comments are auto-generated, so don't worry about +# neatness when editing the file. Natural Docs will clean it up the next +# time it is run. When working with groups, just deal with the braces and +# forget about the indentation and comments. +# +# -------------------------------------------------------------------------- + + +File: OpenLayers (OpenLayers.js) + +Group: OpenLayers { + + File: Ajax (no auto-title, OpenLayers/Ajax.js) + File: Base Types (no auto-title, OpenLayers/BaseTypes.js) + File: Console (no auto-title, OpenLayers/Console.js) + + Group: Control { + + File: Control (no auto-title, OpenLayers/Control.js) + File: ArgParser (no auto-title, OpenLayers/Control/ArgParser.js) + File: ZoomToMaxExtent (no auto-title, OpenLayers/Control/ZoomToMaxExtent.js) + File: OverviewMap (no auto-title, OpenLayers/Control/OverviewMap.js) + File: DragPan (no auto-title, OpenLayers/Control/DragPan.js) + File: DrawFeature (no auto-title, OpenLayers/Control/DrawFeature.js) + File: EditingToolbar (no auto-title, OpenLayers/Control/EditingToolbar.js) + File: KeyboardDefaults (no auto-title, OpenLayers/Control/KeyboardDefaults.js) + File: LayerSwitcher (no auto-title, OpenLayers/Control/LayerSwitcher.js) + File: MouseDefaults (no auto-title, OpenLayers/Control/MouseDefaults.js) + File: MousePosition (no auto-title, OpenLayers/Control/MousePosition.js) + File: MouseToolbar (no auto-title, OpenLayers/Control/MouseToolbar.js) + File: Navigation (no auto-title, OpenLayers/Control/Navigation.js) + File: NavToolbar (no auto-title, OpenLayers/Control/NavToolbar.js) + File: Panel (no auto-title, OpenLayers/Control/Panel.js) + File: PanZoomBar (no auto-title, OpenLayers/Control/PanZoomBar.js) + File: Permalink (no auto-title, OpenLayers/Control/Permalink.js) + File: Scale (no auto-title, OpenLayers/Control/Scale.js) + File: SelectFeature (no auto-title, OpenLayers/Control/SelectFeature.js) + File: ZoomBox (no auto-title, OpenLayers/Control/ZoomBox.js) + File: PanZoom (OpenLayers/Control/PanZoom.js) + } # Group: Control + + File: Events (no auto-title, OpenLayers/Events.js) + + Group: Feature { + + File: Feature (no auto-title, OpenLayers/Feature.js) + File: WFS (no auto-title, OpenLayers/Feature/WFS.js) + File: Vector (no auto-title, OpenLayers/Feature/Vector.js) + } # Group: Feature + + Group: Format { + + File: Format (no auto-title, OpenLayers/Format.js) + File: GeoRSS (OpenLayers/Format/GeoRSS.js) + File: GML (OpenLayers/Format/GML.js) + File: KML (OpenLayers/Format/KML.js) + File: WFS (OpenLayers/Format/WFS.js) + File: WKT (no auto-title, OpenLayers/Format/WKT.js) + } # Group: Format + + Group: Geometry { + + File: Geometry (no auto-title, OpenLayers/Geometry.js) + File: Collection (no auto-title, OpenLayers/Geometry/Collection.js) + File: Curve (OpenLayers/Geometry/Curve.js) + File: LinearRing (OpenLayers/Geometry/LinearRing.js) + File: LineString (no auto-title, OpenLayers/Geometry/LineString.js) + File: MultiLineString (no auto-title, OpenLayers/Geometry/MultiLineString.js) + File: MultiPoint (no auto-title, OpenLayers/Geometry/MultiPoint.js) + File: MultiPolygon (no auto-title, OpenLayers/Geometry/MultiPolygon.js) + File: Point (no auto-title, OpenLayers/Geometry/Point.js) + File: Polygon (no auto-title, OpenLayers/Geometry/Polygon.js) + File: Rectangle (OpenLayers/Geometry/Rectangle.js) + File: Surface (OpenLayers/Geometry/Surface.js) + } # Group: Geometry + + Group: Handler { + + File: Handler (no auto-title, OpenLayers/Handler.js) + File: Box (OpenLayers/Handler/Box.js) + File: Drag (no auto-title, OpenLayers/Handler/Drag.js) + File: Feature (no auto-title, OpenLayers/Handler/Feature.js) + File: Keyboard (no auto-title, OpenLayers/Handler/Keyboard.js) + File: MouseWheel (no auto-title, OpenLayers/Handler/MouseWheel.js) + File: Path (no auto-title, OpenLayers/Handler/Path.js) + File: Point (no auto-title, OpenLayers/Handler/Point.js) + File: Polygon (OpenLayers/Handler/Polygon.js) + } # Group: Handler + + File: Icon (no auto-title, OpenLayers/Icon.js) + + Group: Layer { + + File: Layer (no auto-title, OpenLayers/Layer.js) + File: Boxes (OpenLayers/Layer/Boxes.js) + File: EventPane (OpenLayers/Layer/EventPane.js) + File: FixedZoomLevels (OpenLayers/Layer/FixedZoomLevels.js) + File: GeoRSS (no auto-title, OpenLayers/Layer/GeoRSS.js) + File: GML (no auto-title, OpenLayers/Layer/GML.js) + File: Grid (OpenLayers/Layer/Grid.js) + File: Image (no auto-title, OpenLayers/Layer/Image.js) + File: MapServer (OpenLayers/Layer/MapServer.js) + File: Markers (no auto-title, OpenLayers/Layer/Markers.js) + File: Text (OpenLayers/Layer/Text.js) + File: Vector (no auto-title, OpenLayers/Layer/Vector.js) + File: WMS (no auto-title, OpenLayers/Layer/WMS.js) + File: WMS.Untiled (no auto-title, OpenLayers/Layer/WMS/Untiled.js) + File: WorldWind (OpenLayers/Layer/WorldWind.js) + } # Group: Layer + + File: Map (no auto-title, OpenLayers/Map.js) + + Group: Marker { + + File: Marker (no auto-title, OpenLayers/Marker.js) + File: Box (no auto-title, OpenLayers/Marker/Box.js) + } # Group: Marker + + Group: Popup { + + File: Popup (no auto-title, OpenLayers/Popup.js) + File: Anchored (no auto-title, OpenLayers/Popup/Anchored.js) + File: AnchoredBubble (OpenLayers/Popup/AnchoredBubble.js) + } # Group: Popup + + Group: Renderer { + + File: Renderer (OpenLayers/Renderer.js) + File: Elements (no auto-title, OpenLayers/Renderer/Elements.js) + File: SVG (no auto-title, OpenLayers/Renderer/SVG.js) + File: VML (no auto-title, OpenLayers/Renderer/VML.js) + } # Group: Renderer + + Group: Tile { + + File: Tile (no auto-title, OpenLayers/Tile.js) + File: Image (no auto-title, OpenLayers/Tile/Image.js) + File: WFS (no auto-title, OpenLayers/Tile/WFS.js) + } # Group: Tile + + File: Util (OpenLayers/Util.js) + } # Group: OpenLayers + +Group: Index { + + Index: Everything + Class Index: Classes + Constant Index: Constants + Function Index: Functions + Property Index: Properties + File Index: Files + Constructor Index: Constructor + } # Group: Index + diff --git a/apidoc_config/OL.css b/apidoc_config/OL.css new file mode 100644 index 0000000000..a397119822 --- /dev/null +++ b/apidoc_config/OL.css @@ -0,0 +1,20 @@ +p { + text-indent: 0; margin-bottom: 1em; +} + +.MGroup { + font-variant: normal; + margin: 0.4em 0 0em 10px +} + +.MTitle { + font-variant: normal; +} + +.CGroup .CTitle { + font-variant: normal; +} + +.SGroup .SEntry { + font-variant: normal; +} \ No newline at end of file diff --git a/apidoc_config/Topics.txt b/apidoc_config/Topics.txt new file mode 100644 index 0000000000..3de15ab0bb --- /dev/null +++ b/apidoc_config/Topics.txt @@ -0,0 +1,108 @@ +Format: 1.35 + +# This is the Natural Docs topics file for this project. If you change anything +# here, it will apply to THIS PROJECT ONLY. If you'd like to change something +# for all your projects, edit the Topics.txt in Natural Docs' Config directory +# instead. + + +Ignore Keywords: + function, functions + func, funcs + procedure, procedures + proc, procs + routine, routines + subroutine, subroutines + sub, subs + method, methods + callback, callbacks + property, properties + prop, props + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Topic Type: [name] +# Alter Topic Type: [name] +# Creates a new topic type or alters one from the main file. Each type gets +# its own index and behavior settings. Its name can have letters, numbers, +# spaces, and these charaters: - / . ' +# +# Plural: [name] +# Sets the plural name of the topic type, if different. +# +# Keywords: +# [keyword] +# [keyword], [plural keyword] +# ... +# Defines or adds to the list of keywords for the topic type. They may only +# contain letters, numbers, and spaces and are not case sensitive. Plural +# keywords are used for list topics. You can redefine keywords found in the +# main topics file. +# +# Index: [yes|no] +# Whether the topics get their own index. Defaults to yes. Everything is +# included in the general index regardless of this setting. +# +# Scope: [normal|start|end|always global] +# How the topics affects scope. Defaults to normal. +# normal - Topics stay within the current scope. +# start - Topics start a new scope for all the topics beneath it, +# like class topics. +# end - Topics reset the scope back to global for all the topics +# beneath it. +# always global - Topics are defined as global, but do not change the scope +# for any other topics. +# +# Class Hierarchy: [yes|no] +# Whether the topics are part of the class hierarchy. Defaults to no. +# +# Variable Type: [yes|no] +# Whether the topics can be a variable type. Defaults to no. +# +# Page Title If First: [yes|no] +# Whether the topic's title becomes the page title if it's the first one in +# a file. Defaults to no. +# +# Break Lists: [yes|no] +# Whether list topics should be broken into individual topics in the output. +# Defaults to no. +# +# Can Group With: [type], [type], ... +# Defines a list of topic types that this one can possibly be grouped with. +# Defaults to none. +#------------------------------------------------------------------------------- + +# The following topics are defined in the main file, if you'd like to alter +# their behavior or add keywords: +# +# Generic, Class, Interface, Section, File, Group, Function, Variable, +# Property, Type, Constant, Enumeration, Event, Delegate, Macro, +# Database, Database Table, Database View, Database Index, Database +# Cursor, Database Trigger, Cookie, Build Target + +# If you add something that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# topics [at] naturaldocs [dot] org. + + +Topic Type: Constructor + + Class Hierarchy: Yes + Keywords: + constructor + initialize + + +Alter Topic Type: Function + + Add Keywords: + apimethod + apifunction + + +Alter Topic Type: Property + + Add Keywords: + apiproperty diff --git a/doc/authors.txt b/doc/authors.txt index 072416d55a..3b43ca2b06 100644 --- a/doc/authors.txt +++ b/doc/authors.txt @@ -1,25 +1,25 @@ -OpenLayers contributors: -Howard Butler -Bertil Chaupis -John Cole -Jeff Dege -Schuyler Erle -Christian López Espínola -John Frank -Sean Gilles -Pierre Giraud -Andreas Hocevar -Philip Lindsay -Corey Puffault -Tim Schaub -Christopher Schmidt -Cameron Shorter -Paul Spencer -James Stembridge -Erik Uzureau -Bill Woodall -Steve Woodbridge - - -OpenLayers is graciously supported by MetaCarta, Inc. -. +OpenLayers contributors: +Howard Butler +Bertil Chaupis +John Cole +Jeff Dege +Schuyler Erle +Christian López Espínola +John Frank +Sean Gilles +Pierre Giraud +Andreas Hocevar +Philip Lindsay +Corey Puffault +Tim Schaub +Christopher Schmidt +Cameron Shorter +Paul Spencer +James Stembridge +Erik Uzureau +Bill Woodall +Steve Woodbridge + + +OpenLayers is graciously supported by MetaCarta, Inc. +. diff --git a/doc/customization b/doc/customization index f4b5b98aa9..61b4184e7c 100644 --- a/doc/customization +++ b/doc/customization @@ -1,49 +1,49 @@ -Customizing OpenLayers -====================== - -OpenLayers is designed to fit many needs -- fitting in alongside all kinds of -various applications which are currently in use. - -Currently, OpenLayers supports a 'theme' option when creating a map. This -theme option allows you to specify the location of a CSS theme which should -be included. - -A default theme is available as an example in the theme/ directory: the setup -is: - - * theme/ - * theme/default/ - * theme/default/style.css - * theme/default/img/ - -Currently, the OpenLayers code does not support class names, and therefore, -it is not possible to control many aspects of OpenLayers code with CSS -classes. However, with this framework in place, we expect to invest time -to make existing features and new features use the CSS theming framework -where apropriate. - - -Class Naming -============ -Elements should have class names which are descriptive of the Javascript -class from which they come. For example, the main layer switcher element -in the OpenLayers.Control.LayerSwitcher would be classed: - - olControlLayerSwitcher - -This would allow users to add to their style.css class in their theme, -changing, for example: - -:: - - .olControlLayerSwitcher input { - width:10px; - } - -Sub elements of a particular control can add to the class name: - -:: - - .olControlLayerSwitcherBaseLabel { - color: red; - } +Customizing OpenLayers +====================== + +OpenLayers is designed to fit many needs -- fitting in alongside all kinds of +various applications which are currently in use. + +Currently, OpenLayers supports a 'theme' option when creating a map. This +theme option allows you to specify the location of a CSS theme which should +be included. + +A default theme is available as an example in the theme/ directory: the setup +is: + + * theme/ + * theme/default/ + * theme/default/style.css + * theme/default/img/ + +Currently, the OpenLayers code does not support class names, and therefore, +it is not possible to control many aspects of OpenLayers code with CSS +classes. However, with this framework in place, we expect to invest time +to make existing features and new features use the CSS theming framework +where apropriate. + + +Class Naming +============ +Elements should have class names which are descriptive of the Javascript +class from which they come. For example, the main layer switcher element +in the OpenLayers.Control.LayerSwitcher would be classed: + + olControlLayerSwitcher + +This would allow users to add to their style.css class in their theme, +changing, for example: + +:: + + .olControlLayerSwitcher input { + width:10px; + } + +Sub elements of a particular control can add to the class name: + +:: + + .olControlLayerSwitcherBaseLabel { + color: red; + } diff --git a/doc/readme.txt b/doc/readme.txt index fd23a71bbe..a675b7c3e6 100644 --- a/doc/readme.txt +++ b/doc/readme.txt @@ -1,3 +1,3 @@ -Automatically generated OpenLayers API documentation is online: - - http://dev.openlayers.org/docs/overview-tree.html +Automatically generated OpenLayers API documentation is online: + + http://dev.openlayers.org/docs/overview-tree.html diff --git a/doc_config/Languages.txt b/doc_config/Languages.txt new file mode 100644 index 0000000000..aa9ce802fe --- /dev/null +++ b/doc_config/Languages.txt @@ -0,0 +1,113 @@ +Format: 1.35 + +# This is the Natural Docs languages file for this project. If you change +# anything here, it will apply to THIS PROJECT ONLY. If you'd like to change +# something for all your projects, edit the Languages.txt in Natural Docs' +# Config directory instead. + + +# You can prevent certain file extensions from being scanned like this: +# Ignore Extensions: [extension] [extension] ... + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Unlike other Natural Docs configuration files, in this file all comments +# MUST be alone on a line. Some languages deal with the # character, so you +# cannot put comments on the same line as content. +# +# Also, all lists are separated with spaces, not commas, again because some +# languages may need to use them. +# +# Language: [name] +# Alter Language: [name] +# Defines a new language or alters an existing one. Its name can use any +# characters. If any of the properties below have an add/replace form, you +# must use that when using Alter Language. +# +# The language Shebang Script is special. It's entry is only used for +# extensions, and files with those extensions have their shebang (#!) lines +# read to determine the real language of the file. Extensionless files are +# always treated this way. +# +# The language Text File is also special. It's treated as one big comment +# so you can put Natural Docs content in them without special symbols. Also, +# if you don't specify a package separator, ignored prefixes, or enum value +# behavior, it will copy those settings from the language that is used most +# in the source tree. +# +# Extensions: [extension] [extension] ... +# [Add/Replace] Extensions: [extension] [extension] ... +# Defines the file extensions of the language's source files. You can +# redefine extensions found in the main languages file. You can use * to +# mean any undefined extension. +# +# Shebang Strings: [string] [string] ... +# [Add/Replace] Shebang Strings: [string] [string] ... +# Defines a list of strings that can appear in the shebang (#!) line to +# designate that it's part of the language. You can redefine strings found +# in the main languages file. +# +# Ignore Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ... +# +# Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# Specifies prefixes that should be ignored when sorting symbols in an +# index. Can be specified in general or for a specific topic type. +# +#------------------------------------------------------------------------------ +# For basic language support only: +# +# Line Comments: [symbol] [symbol] ... +# Defines a space-separated list of symbols that are used for line comments, +# if any. +# +# Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ... +# Defines a space-separated list of symbol pairs that are used for block +# comments, if any. +# +# Package Separator: [symbol] +# Defines the default package separator symbol. The default is a dot. +# +# [Topic Type] Prototype Enders: [symbol] [symbol] ... +# When defined, Natural Docs will attempt to get a prototype from the code +# immediately following the topic type. It stops when it reaches one of +# these symbols. Use \n for line breaks. +# +# Line Extender: [symbol] +# Defines the symbol that allows a prototype to span multiple lines if +# normally a line break would end it. +# +# Enum Values: [global|under type|under parent] +# Defines how enum values are referenced. The default is global. +# global - Values are always global, referenced as 'value'. +# under type - Values are under the enum type, referenced as +# 'package.enum.value'. +# under parent - Values are under the enum's parent, referenced as +# 'package.value'. +# +# Perl Package: [perl package] +# Specifies the Perl package used to fine-tune the language behavior in ways +# too complex to do in this file. +# +#------------------------------------------------------------------------------ +# For full language support only: +# +# Full Language Support: [perl package] +# Specifies the Perl package that has the parsing routines necessary for full +# language support. +# +#------------------------------------------------------------------------------- + +# The following languages are defined in the main file, if you'd like to alter +# them: +# +# Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python, +# PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile, +# ActionScript, ColdFusion, R, Fortran + +# If you add a language that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# languages [at] naturaldocs [dot] org. diff --git a/doc_config/Menu.txt b/doc_config/Menu.txt new file mode 100644 index 0000000000..df42f638bd --- /dev/null +++ b/doc_config/Menu.txt @@ -0,0 +1,177 @@ +Format: 1.35 + + +Title: OpenLayers +SubTitle: JavaScript Mapping Library + +# You can add a footer to your documentation like this: +# Footer: [text] +# If you want to add a copyright notice, this would be the place to do it. + + +# -------------------------------------------------------------------------- +# +# Cut and paste the lines below to change the order in which your files +# appear on the menu. Don't worry about adding or removing files, Natural +# Docs will take care of that. +# +# You can further organize the menu by grouping the entries. Add a +# "Group: [name] {" line to start a group, and add a "}" to end it. +# +# You can add text and web links to the menu by adding "Text: [text]" and +# "Link: [name] ([URL])" lines, respectively. +# +# The formatting and comments are auto-generated, so don't worry about +# neatness when editing the file. Natural Docs will clean it up the next +# time it is run. When working with groups, just deal with the braces and +# forget about the indentation and comments. +# +# -------------------------------------------------------------------------- + + +File: OpenLayers (OpenLayers.js) + +Group: OpenLayers { + + File: Ajax (no auto-title, OpenLayers/Ajax.js) + File: Base Types (no auto-title, OpenLayers/BaseTypes.js) + File: Console (no auto-title, OpenLayers/Console.js) + + Group: Control { + + File: Control (no auto-title, OpenLayers/Control.js) + File: ArgParser (no auto-title, OpenLayers/Control/ArgParser.js) + File: ZoomToMaxExtent (no auto-title, OpenLayers/Control/ZoomToMaxExtent.js) + File: OverviewMap (no auto-title, OpenLayers/Control/OverviewMap.js) + File: DragPan (no auto-title, OpenLayers/Control/DragPan.js) + File: DrawFeature (no auto-title, OpenLayers/Control/DrawFeature.js) + File: EditingToolbar (no auto-title, OpenLayers/Control/EditingToolbar.js) + File: KeyboardDefaults (no auto-title, OpenLayers/Control/KeyboardDefaults.js) + File: LayerSwitcher (no auto-title, OpenLayers/Control/LayerSwitcher.js) + File: MouseDefaults (no auto-title, OpenLayers/Control/MouseDefaults.js) + File: MousePosition (no auto-title, OpenLayers/Control/MousePosition.js) + File: MouseToolbar (no auto-title, OpenLayers/Control/MouseToolbar.js) + File: Navigation (no auto-title, OpenLayers/Control/Navigation.js) + File: NavToolbar (no auto-title, OpenLayers/Control/NavToolbar.js) + File: Panel (no auto-title, OpenLayers/Control/Panel.js) + File: PanZoomBar (no auto-title, OpenLayers/Control/PanZoomBar.js) + File: Permalink (no auto-title, OpenLayers/Control/Permalink.js) + File: Scale (no auto-title, OpenLayers/Control/Scale.js) + File: SelectFeature (no auto-title, OpenLayers/Control/SelectFeature.js) + File: ZoomBox (no auto-title, OpenLayers/Control/ZoomBox.js) + File: PanZoom (OpenLayers/Control/PanZoom.js) + } # Group: Control + + File: Events (no auto-title, OpenLayers/Events.js) + + Group: Feature { + + File: Feature (no auto-title, OpenLayers/Feature.js) + File: WFS (no auto-title, OpenLayers/Feature/WFS.js) + File: Vector (no auto-title, OpenLayers/Feature/Vector.js) + } # Group: Feature + + Group: Format { + + File: Format (no auto-title, OpenLayers/Format.js) + File: GeoRSS (OpenLayers/Format/GeoRSS.js) + File: GML (OpenLayers/Format/GML.js) + File: KML (OpenLayers/Format/KML.js) + File: WFS (OpenLayers/Format/WFS.js) + File: WKT (no auto-title, OpenLayers/Format/WKT.js) + } # Group: Format + + Group: Geometry { + + File: Geometry (no auto-title, OpenLayers/Geometry.js) + File: Collection (no auto-title, OpenLayers/Geometry/Collection.js) + File: Curve (OpenLayers/Geometry/Curve.js) + File: LinearRing (OpenLayers/Geometry/LinearRing.js) + File: LineString (no auto-title, OpenLayers/Geometry/LineString.js) + File: MultiLineString (no auto-title, OpenLayers/Geometry/MultiLineString.js) + File: MultiPoint (no auto-title, OpenLayers/Geometry/MultiPoint.js) + File: MultiPolygon (no auto-title, OpenLayers/Geometry/MultiPolygon.js) + File: Point (no auto-title, OpenLayers/Geometry/Point.js) + File: Polygon (no auto-title, OpenLayers/Geometry/Polygon.js) + File: Rectangle (OpenLayers/Geometry/Rectangle.js) + File: Surface (OpenLayers/Geometry/Surface.js) + } # Group: Geometry + + Group: Handler { + + File: Handler (no auto-title, OpenLayers/Handler.js) + File: Box (OpenLayers/Handler/Box.js) + File: Drag (no auto-title, OpenLayers/Handler/Drag.js) + File: Feature (no auto-title, OpenLayers/Handler/Feature.js) + File: Keyboard (no auto-title, OpenLayers/Handler/Keyboard.js) + File: MouseWheel (no auto-title, OpenLayers/Handler/MouseWheel.js) + File: Path (no auto-title, OpenLayers/Handler/Path.js) + File: Point (no auto-title, OpenLayers/Handler/Point.js) + File: Polygon (OpenLayers/Handler/Polygon.js) + } # Group: Handler + + File: Icon (no auto-title, OpenLayers/Icon.js) + + Group: Layer { + + File: Layer (no auto-title, OpenLayers/Layer.js) + File: Boxes (OpenLayers/Layer/Boxes.js) + File: EventPane (OpenLayers/Layer/EventPane.js) + File: FixedZoomLevels (OpenLayers/Layer/FixedZoomLevels.js) + File: GeoRSS (no auto-title, OpenLayers/Layer/GeoRSS.js) + File: GML (no auto-title, OpenLayers/Layer/GML.js) + File: Grid (OpenLayers/Layer/Grid.js) + File: Image (no auto-title, OpenLayers/Layer/Image.js) + File: MapServer (OpenLayers/Layer/MapServer.js) + File: Markers (no auto-title, OpenLayers/Layer/Markers.js) + File: Text (OpenLayers/Layer/Text.js) + File: Vector (no auto-title, OpenLayers/Layer/Vector.js) + File: WMS (no auto-title, OpenLayers/Layer/WMS.js) + File: WMS.Untiled (no auto-title, OpenLayers/Layer/WMS/Untiled.js) + File: WorldWind (OpenLayers/Layer/WorldWind.js) + } # Group: Layer + + File: Map (no auto-title, OpenLayers/Map.js) + + Group: Marker { + + File: Marker (no auto-title, OpenLayers/Marker.js) + File: Box (no auto-title, OpenLayers/Marker/Box.js) + } # Group: Marker + + Group: Popup { + + File: Popup (no auto-title, OpenLayers/Popup.js) + File: Anchored (no auto-title, OpenLayers/Popup/Anchored.js) + File: AnchoredBubble (OpenLayers/Popup/AnchoredBubble.js) + } # Group: Popup + + Group: Renderer { + + File: Renderer (OpenLayers/Renderer.js) + File: Elements (no auto-title, OpenLayers/Renderer/Elements.js) + File: SVG (no auto-title, OpenLayers/Renderer/SVG.js) + File: VML (no auto-title, OpenLayers/Renderer/VML.js) + } # Group: Renderer + + Group: Tile { + + File: Tile (no auto-title, OpenLayers/Tile.js) + File: Image (no auto-title, OpenLayers/Tile/Image.js) + File: WFS (no auto-title, OpenLayers/Tile/WFS.js) + } # Group: Tile + + File: Util (OpenLayers/Util.js) + } # Group: OpenLayers + +Group: Index { + + Index: Everything + Class Index: Classes + Constant Index: Constants + Function Index: Functions + Property Index: Properties + File Index: Files + Constructor Index: Constructor + } # Group: Index + diff --git a/doc_config/OL.css b/doc_config/OL.css new file mode 100644 index 0000000000..a397119822 --- /dev/null +++ b/doc_config/OL.css @@ -0,0 +1,20 @@ +p { + text-indent: 0; margin-bottom: 1em; +} + +.MGroup { + font-variant: normal; + margin: 0.4em 0 0em 10px +} + +.MTitle { + font-variant: normal; +} + +.CGroup .CTitle { + font-variant: normal; +} + +.SGroup .SEntry { + font-variant: normal; +} \ No newline at end of file diff --git a/doc_config/Topics.txt b/doc_config/Topics.txt new file mode 100644 index 0000000000..e7dc0c6fdc --- /dev/null +++ b/doc_config/Topics.txt @@ -0,0 +1,105 @@ +Format: 1.35 + +# This is the Natural Docs topics file for this project. If you change anything +# here, it will apply to THIS PROJECT ONLY. If you'd like to change something +# for all your projects, edit the Topics.txt in Natural Docs' Config directory +# instead. + + +# If you'd like to prevent keywords from being recognized by Natural Docs, you +# can do it like this: +# Ignore Keywords: [keyword], [keyword], ... +# +# Or you can use the list syntax like how they are defined: +# Ignore Keywords: +# [keyword] +# [keyword], [plural keyword] +# ... + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Topic Type: [name] +# Alter Topic Type: [name] +# Creates a new topic type or alters one from the main file. Each type gets +# its own index and behavior settings. Its name can have letters, numbers, +# spaces, and these charaters: - / . ' +# +# Plural: [name] +# Sets the plural name of the topic type, if different. +# +# Keywords: +# [keyword] +# [keyword], [plural keyword] +# ... +# Defines or adds to the list of keywords for the topic type. They may only +# contain letters, numbers, and spaces and are not case sensitive. Plural +# keywords are used for list topics. You can redefine keywords found in the +# main topics file. +# +# Index: [yes|no] +# Whether the topics get their own index. Defaults to yes. Everything is +# included in the general index regardless of this setting. +# +# Scope: [normal|start|end|always global] +# How the topics affects scope. Defaults to normal. +# normal - Topics stay within the current scope. +# start - Topics start a new scope for all the topics beneath it, +# like class topics. +# end - Topics reset the scope back to global for all the topics +# beneath it. +# always global - Topics are defined as global, but do not change the scope +# for any other topics. +# +# Class Hierarchy: [yes|no] +# Whether the topics are part of the class hierarchy. Defaults to no. +# +# Variable Type: [yes|no] +# Whether the topics can be a variable type. Defaults to no. +# +# Page Title If First: [yes|no] +# Whether the topic's title becomes the page title if it's the first one in +# a file. Defaults to no. +# +# Break Lists: [yes|no] +# Whether list topics should be broken into individual topics in the output. +# Defaults to no. +# +# Can Group With: [type], [type], ... +# Defines a list of topic types that this one can possibly be grouped with. +# Defaults to none. +#------------------------------------------------------------------------------- + +# The following topics are defined in the main file, if you'd like to alter +# their behavior or add keywords: +# +# Generic, Class, Interface, Section, File, Group, Function, Variable, +# Property, Type, Constant, Enumeration, Event, Delegate, Macro, +# Database, Database Table, Database View, Database Index, Database +# Cursor, Database Trigger, Cookie, Build Target + +# If you add something that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# topics [at] naturaldocs [dot] org. + + +Topic Type: Constructor + + Class Hierarchy: Yes + Keywords: + constructor + initialize + + +Alter Topic Type: Function + + Add Keywords: + apimethod + apifunction + + +Alter Topic Type: Property + + Add Keywords: + apiproperty diff --git a/lib/OpenLayers.js b/lib/OpenLayers.js index 50440c8003..d383df5f8d 100644 --- a/lib/OpenLayers.js +++ b/lib/OpenLayers.js @@ -6,9 +6,6 @@ * @requires OpenLayers/BaseTypes.js */ -//// -/// This blob sucks in all the files in uncompressed form for ease of use -/// (function() { /** * Before creating the OpenLayers namespace, check to see if @@ -17,22 +14,25 @@ * case with single file builds. */ var singleFile = (typeof OpenLayers == "object" && OpenLayers.singleFile); + /** + * Namespace: OpenLayers * The OpenLayers object provides a namespace for all things OpenLayers - * @type Object */ OpenLayers = { /** - * @type String - * @private + * Property: _scriptName + * {String} Relative path of this script. */ _scriptName: (!singleFile) ? "lib/OpenLayers.js" : "OpenLayers.js", /** - * @type String - * @returns Path to this script - * @private + * Function: _getScriptLocation + * Return the path to this script. + * + * Return: + * Path to this script */ _getScriptLocation: function () { var scriptLocation = ""; @@ -184,4 +184,8 @@ if (allScriptTags) document.write(allScriptTags); } })(); + +/** + * Constant: VERSION_NUMBER + */ OpenLayers.VERSION_NUMBER="$Revision$"; diff --git a/lib/OpenLayers/Ajax.js b/lib/OpenLayers/Ajax.js index f776403603..e15fa1e13c 100644 --- a/lib/OpenLayers/Ajax.js +++ b/lib/OpenLayers/Ajax.js @@ -37,16 +37,19 @@ OpenLayers.nullHandler = function(request) { alert("Unhandled request return " + request.statusText); }; -/** Background load a document -* -* @param {String} uri URI of source doc -* @param {String} params Params on get (doesnt seem to work) -* @param {Object} caller object which gets callbacks -* @param {Function} onComplete callback for success -* @param {Function} onFailure callback for failure -* -* Both callbacks optional (though silly) -*/ +/** + * Function: loadURL + * Background load a document. + * + * Parameters: + * uri - {String} URI of source doc + * params - {String} Params on get (doesnt seem to work) + * caller - {Object} object which gets callbacks + * onComplete - {Function} callback for success + * onFailure - {Function} callback for failure + * + * Both callbacks optional (though silly) + */ OpenLayers.loadURL = function(uri, params, caller, onComplete, onFailure) { @@ -70,12 +73,16 @@ OpenLayers.loadURL = function(uri, params, caller, ); }; -/** Parse XML into a doc structure -* @param {String} text -* -* @returns Parsed Ajax Response ?? -* @type ? -*/ +/** + * Function: parseXMLString + * Parse XML into a doc structure + * + * Parameters: + * text - {String} + * + * Return: + * {?} Parsed AJAX Responsev + */ OpenLayers.parseXMLString = function(text) { //MS sucks, if the server is bad it dies @@ -108,224 +115,413 @@ OpenLayers.parseXMLString = function(text) { return ajaxResponse; }; + +/** + * Namespace: OpenLayers.Ajax + */ OpenLayers.Ajax = { - emptyFunction: function () {}, - getTransport: function() { - return OpenLayers.Util.Try( - function() {return new ActiveXObject('Msxml2.XMLHTTP')}, - function() {return new ActiveXObject('Microsoft.XMLHTTP')}, - function() {return new XMLHttpRequest()} - ) || false; - }, + /** + * Method: emptyFunction + */ + emptyFunction: function () {}, - activeRequestCount: 0 + /** + * Method: getTransport + * + * Return: + * {Object} Transport mechanism for whichever browser we're in, or false if + * none available. + */ + getTransport: function() { + return OpenLayers.Util.Try( + function() {return new ActiveXObject('Msxml2.XMLHTTP')}, + function() {return new ActiveXObject('Microsoft.XMLHTTP')}, + function() {return new XMLHttpRequest()} + ) || false; + }, + + /** + * Property: activeRequestCount + * {Integer} + */ + activeRequestCount: 0 }; +/** + * Namespace: OpenLayers.Ajax.Responders + * {Object} + */ OpenLayers.Ajax.Responders = { - responders: [], + + /** + * Property: responders + * {Array} + */ + responders: [], - register: function(responderToAdd) { - for (var i = 0; i < this.responders.length; i++) - if (responderToAdd == this.responders[i]) - return; - this.responders.push(responderToAdd); - }, + /** + * Method: register + * + * Parameters: + * responderToAdd - {?} + */ + register: function(responderToAdd) { + for (var i = 0; i < this.responders.length; i++) + if (responderToAdd == this.responders[i]) + return; + this.responders.push(responderToAdd); + }, - dispatch: function(callback, request, transport, json) { - for (var i = 0; i < this.responders.length; i++) { - responder = this.responders[i]; - if (responder[callback] && typeof responder[callback] == 'function') { - try { - responder[callback].apply(responder, [request, transport, json]); - } catch (e) {} - } + /** + * Method: dispatch + * + * Parameters: + * callback - {?} + * request - {?} + * transport - {?} + * json - {?} + */ + dispatch: function(callback, request, transport, json) { + for (var i = 0; i < this.responders.length; i++) { + responder = this.responders[i]; + + if (responder[callback] && + typeof responder[callback] == 'function') { + try { + responder[callback].apply(responder, + [request, transport, json]); + } catch (e) {} + } + } } - } }; OpenLayers.Ajax.Responders.register({ - onCreate: function() { - OpenLayers.Ajax.activeRequestCount++; - }, + /** + * Function: onCreate + */ + onCreate: function() { + OpenLayers.Ajax.activeRequestCount++; + }, - onComplete: function() { - OpenLayers.Ajax.activeRequestCount--; - } + /** + * Function: onComplete + */ + onComplete: function() { + OpenLayers.Ajax.activeRequestCount--; + } }); +/** + * Namespace: OpenLayers.Ajax.Base + * {Object} + */ OpenLayers.Ajax.Base = function() {}; OpenLayers.Ajax.Base.prototype = { - setOptions: function(options) { - this.options = { - method: 'post', - asynchronous: true, - parameters: '' + + /** + * Function: setOptions + * + * Parameters: + * options - {Object} + */ + setOptions: function(options) { + this.options = { + 'method': 'post', + 'asynchronous': true, + 'parameters': '' + }; + OpenLayers.Util.extend(this.options, options || {}); + }, + + /** + * Function: responseIsSuccess + * + * Return: + * {Boolean} + */ + responseIsSuccess: function() { + return this.transport.status == undefined || + this.transport.status == 0 || + (this.transport.status >= 200 && this.transport.status < 300); + }, + + /** + * Function: responseIsFailure + * + * Return: + * {Boolean} + */ + responseIsFailure: function() { + return !this.responseIsSuccess(); } - OpenLayers.Util.extend(this.options, options || {}); - }, - - responseIsSuccess: function() { - return this.transport.status == undefined - || this.transport.status == 0 - || (this.transport.status >= 200 && this.transport.status < 300); - }, - - responseIsFailure: function() { - return !this.responseIsSuccess(); - } -} +}; +/** + * Class: OpenLayers.Ajax.Request + * + * Inherit: + * - + */ OpenLayers.Ajax.Request = OpenLayers.Class.create(); + +/** + * Property: Events + * {Array(String)} + */ OpenLayers.Ajax.Request.Events = ['Uninitialized', 'Loading', 'Loaded', 'Interactive', 'Complete']; -OpenLayers.Ajax.Request.prototype = OpenLayers.Class.inherit( OpenLayers.Ajax.Base, { - initialize: function(url, options) { - this.transport = OpenLayers.Ajax.getTransport(); - this.setOptions(options); - this.request(url); - }, - - request: function(url) { - var parameters = this.options.parameters || ''; - if (parameters.length > 0) parameters += '&_='; - - try { - this.url = url; - if (this.options.method == 'get' && parameters.length > 0) - this.url += (this.url.match(/\?/) ? '&' : '?') + parameters; - - OpenLayers.Ajax.Responders.dispatch('onCreate', this, this.transport); - - this.transport.open(this.options.method, this.url, - this.options.asynchronous); - - if (this.options.asynchronous) { - this.transport.onreadystatechange = this.onStateChange.bind(this); - setTimeout((function() {this.respondToReadyState(1)}).bind(this), 10); - } - - this.setRequestHeaders(); - - var body = this.options.postBody ? this.options.postBody : parameters; - this.transport.send(this.options.method == 'post' ? body : null); - - /* Force Firefox to handle ready state 4 for synchronous requests */ - if (!this.options.asynchronous && this.transport.overrideMimeType) { - this.onStateChange(); - } - - } catch (e) { - this.dispatchException(e); - } - }, - - setRequestHeaders: function() { - var requestHeaders = - ['X-Requested-With', 'XMLHttpRequest', - 'X-Prototype-Version', 'OpenLayers']; - - if (this.options.method == 'post' && !this.options.postBody) { - requestHeaders.push('Content-type', - 'application/x-www-form-urlencoded'); - - /* Force "Connection: close" for Mozilla browsers to work around - * a bug where XMLHttpReqeuest sends an incorrect Content-length - * header. See Mozilla Bugzilla #246651. +OpenLayers.Ajax.Request.prototype = + OpenLayers.Class.inherit( OpenLayers.Ajax.Base, { + + /** + * Constructor: OpenLayers.Ajax.Request + * + * Parameters: + * url - {String} + * options - {Object} */ - if (this.transport.overrideMimeType) - requestHeaders.push('Connection', 'close'); + initialize: function(url, options) { + this.transport = OpenLayers.Ajax.getTransport(); + this.setOptions(options); + this.request(url); + }, + + /** + * Method: request + * + * Parameters: + * url - {String} + */ + request: function(url) { + var parameters = this.options.parameters || ''; + if (parameters.length > 0) parameters += '&_='; + + try { + this.url = url; + if (this.options.method == 'get' && parameters.length > 0) { + this.url += (this.url.match(/\?/) ? '&' : '?') + parameters; + } + + OpenLayers.Ajax.Responders.dispatch('onCreate', + this, + this.transport); + + this.transport.open(this.options.method, + this.url, + this.options.asynchronous); + + if (this.options.asynchronous) { + this.transport.onreadystatechange = + this.onStateChange.bind(this); + + setTimeout((function() { + this.respondToReadyState(1) + }).bind(this), 10); + } + + this.setRequestHeaders(); + + var body = this.options.postBody ? this.options.postBody + : parameters; + this.transport.send(this.options.method == 'post' ? body : null); + + // Force Firefox to handle ready state 4 for synchronous requests + if (!this.options.asynchronous && + this.transport.overrideMimeType) { + + this.onStateChange(); + } + + } catch (e) { + this.dispatchException(e); + } + }, + + /** + * Method: setRequestHeaders + */ + setRequestHeaders: function() { + var requestHeaders = [ + 'X-Requested-With', + 'XMLHttpRequest', + 'X-Prototype-Version', + 'OpenLayers' + ]; + + if (this.options.method == 'post' && !this.options.postBody) { + requestHeaders.push('Content-type', + 'application/x-www-form-urlencoded'); + + // Force "Connection: close" for Mozilla browsers to work around + // a bug where XMLHttpReqeuest sends an incorrect Content-length + // header. See Mozilla Bugzilla #246651. + if (this.transport.overrideMimeType) { + requestHeaders.push('Connection', 'close'); + } + } + + if (this.options.requestHeaders) { + requestHeaders.push.apply(requestHeaders, + this.options.requestHeaders); + } + + for (var i = 0; i < requestHeaders.length; i += 2) { + this.transport.setRequestHeader(requestHeaders[i], + requestHeaders[i+1]); + } + }, + + /** + * Method: onStateChange + */ + onStateChange: function() { + var readyState = this.transport.readyState; + if (readyState != 1) { + this.respondToReadyState(this.transport.readyState); + } + }, + + /** + * Method: header + * + * Return: + * {?} + */ + header: function(name) { + try { + return this.transport.getResponseHeader(name); + } catch (e) {} + }, + + /** + * Method: evalJSON + * + * Return: + * {?} + */ + evalJSON: function() { + try { + return eval(this.header('X-JSON')); + } catch (e) {} + }, + + /** + * Method: evalResponse + * + * Return: + * {?} + */ + evalResponse: function() { + try { + return eval(this.transport.responseText); + } catch (e) { + this.dispatchException(e); + } + }, + + /** + * Method: respondToReadyState + * + * Parameters: + * readyState - {?} + */ + respondToReadyState: function(readyState) { + var event = OpenLayers.Ajax.Request.Events[readyState]; + var transport = this.transport, json = this.evalJSON(); + + if (event == 'Complete') { + try { + var responseSuccess = this.responseIsSuccess() ? 'Success' + : 'Failure'; + + (this.options['on' + this.transport.status] || + this.options['on' + responseSuccess] || + OpenLayers.Ajax.emptyFunction)(transport, json); + } catch (e) { + this.dispatchException(e); + } + + var contentType = this.header('Content-type') || ''; + if (contentType.match(/^text\/javascript/i)) { + this.evalResponse(); + } + } + + try { + (this.options['on' + event] || + OpenLayers.Ajax.emptyFunction)(transport, json); + OpenLayers.Ajax.Responders.dispatch('on' + event, + this, + transport, + json); + } catch (e) { + this.dispatchException(e); + } + + // Avoid memory leak in MSIE: clean up the oncomplete event handler + if (event == 'Complete') { + this.transport.onreadystatechange = OpenLayers.Ajax.emptyFunction; + } + }, + + /** + * Method: dispatchException + * + * Parameters: + * exception - {?} + */ + dispatchException: function(exception) { + if (this.options.onException) { + this.options.onException(this, exception); + } else { + // if we get here, Responders.dispatch('onException') will never + // be called. too bad. we should probably take out the Responders + // stuff anyway. + throw exception; + } + OpenLayers.Ajax.Responders.dispatch('onException', this, exception); } - - if (this.options.requestHeaders) - requestHeaders.push.apply(requestHeaders, this.options.requestHeaders); - - for (var i = 0; i < requestHeaders.length; i += 2) - this.transport.setRequestHeader(requestHeaders[i], requestHeaders[i+1]); - }, - - onStateChange: function() { - var readyState = this.transport.readyState; - if (readyState != 1) - this.respondToReadyState(this.transport.readyState); - }, - - header: function(name) { - try { - return this.transport.getResponseHeader(name); - } catch (e) {} - }, - - evalJSON: function() { - try { - return eval(this.header('X-JSON')); - } catch (e) {} - }, - - evalResponse: function() { - try { - return eval(this.transport.responseText); - } catch (e) { - this.dispatchException(e); - } - }, - - respondToReadyState: function(readyState) { - var event = OpenLayers.Ajax.Request.Events[readyState]; - var transport = this.transport, json = this.evalJSON(); - - if (event == 'Complete') { - try { - (this.options['on' + this.transport.status] - || this.options['on' + (this.responseIsSuccess() ? 'Success' : 'Failure')] - || OpenLayers.Ajax.emptyFunction)(transport, json); - } catch (e) { - this.dispatchException(e); - } - - if ((this.header('Content-type') || '').match(/^text\/javascript/i)) - this.evalResponse(); - } - - try { - (this.options['on' + event] || OpenLayers.Ajax.emptyFunction)(transport, json); - OpenLayers.Ajax.Responders.dispatch('on' + event, this, transport, json); - } catch (e) { - this.dispatchException(e); - } - - /* Avoid memory leak in MSIE: clean up the oncomplete event handler */ - if (event == 'Complete') - this.transport.onreadystatechange = OpenLayers.Ajax.emptyFunction; - }, - - dispatchException: function(exception) { - if (this.options.onException) { - this.options.onException(this, exception); - } else { - // if we get here, Responders.dispatch('onException') will never - // be called. too bad. we should probably take out the Responders - // stuff anyway. - throw exception; - } - OpenLayers.Ajax.Responders.dispatch('onException', this, exception); - } + }); -OpenLayers.Ajax.getElementsByTagNameNS = function(parentnode, nsuri, nsprefix, tagname) { - return parentnode.getElementsByTagNameNS ? - parentnode.getElementsByTagNameNS(nsuri, tagname) - : parentnode.getElementsByTagName(nsprefix + ':' + tagname); -} +/** + * Function: getElementsByTagNameNS + * + * Parameters: + * parentnode - {?} + * nsuri - {?} + * nsprefix - {?} + * tagname - {?} + * + * Return: + * {?} + */ +OpenLayers.Ajax.getElementsByTagNameNS = function(parentnode, nsuri, + nsprefix, tagname) { + var elem = null; + if (parentnode.getElementsByTagNameNS) { + elem = parentnode.getElementsByTagNameNS(nsuri, tagname); + } else { + elem = parentnode.getElementsByTagName(nsprefix + ':' + tagname); + } + return elem; +}; + /** + * Function: serializeXMLToString * Wrapper function around XMLSerializer, which doesn't exist/work in - * IE/Safari. We need to come up with a way to serialize in those browser: - * for now, these browsers will just fail. - * #535, #536 + * IE/Safari. We need to come up with a way to serialize in those browser: + * for now, these browsers will just fail. #535, #536 * - * @param {XMLNode} xmldom xml dom to serialize + * Parameters: + * xmldom {XMLNode} xml dom to serialize + * + * Return: + * {?} */ OpenLayers.Ajax.serializeXMLToString = function(xmldom) { var serializer = new XMLSerializer(); diff --git a/lib/OpenLayers/BaseTypes.js b/lib/OpenLayers/BaseTypes.js index 70eb1e53c9..dba8aa955e 100644 --- a/lib/OpenLayers/BaseTypes.js +++ b/lib/OpenLayers/BaseTypes.js @@ -2,11 +2,25 @@ * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ +/** + * Header: OpenLayers Base Types + * Basic types in OpenLayers are described here. + */ -/* OpenLayers.Class metaclass */ +/** + * Namespace: OpenLayers.Class + * Contains functions to create OpenLayers style classes. + */ OpenLayers.Class = { isPrototype: function () {}, // magic anonymous value + /** + * APIFunction: create + * Create an OpenLayers style class + * + * Return: + * An OpenLayers class + */ create: function() { return function() { if (arguments && arguments[0] != OpenLayers.Class.isPrototype) @@ -14,6 +28,16 @@ OpenLayers.Class = { } }, + /** + * APIFunction: inherit + * Inherit from one or more OpenLayers style classes + * + * Parameters: + * class - One or more classes can be provided as arguments + * + * Return: + * An object prototype + */ inherit: function () { var superClass = arguments[0]; var proto = new superClass(OpenLayers.Class.isPrototype); @@ -54,52 +78,73 @@ OpenLayers.Class = { *********************/ /** - * @class - * + * Class: OpenLayers.Pixel * This class represents a screen coordinate, in x and y coordinates */ OpenLayers.Pixel = OpenLayers.Class.create(); OpenLayers.Pixel.prototype = { - /** @type float */ + /** + * APIProperty: x + * {Number} The x coordinate + */ x: 0.0, - /** @type float */ + /** + * APIProperty: x + * {Number} The x coordinate + */ y: 0.0, - /** - * @constructor - * - * @param {float} x - * @param {float} y - */ + /** + * Constructor: OpenLayers.Pixel + * Create a new OpenLayers.Pixel instance + * + * Parameters: + * x - {Number} The x coordinate + * y - {Number} The y coordinate + * + * Return: + * An instance of OpenLayers.Pixel + */ initialize: function(x, y) { this.x = parseFloat(x); this.y = parseFloat(y); }, /** - * @return string representation of Pixel. ex: "x=200.4,y=242.2" - * @type str - */ + * Method: toString + * Cast this object into a string + * + * Return: + * {String} The string representation of Pixel. ex: "x=200.4,y=242.2" + */ toString:function() { return ("x=" + this.x + ",y=" + this.y); }, /** - * @type OpenLayers.Pixel + * APIMethod: clone + * Return a clone of this pixel object + * + * Return: + * {} A clone pixel */ clone:function() { return new OpenLayers.Pixel(this.x, this.y); }, - /** - * @param {OpenLayers.Pixel} px - * - * @return whether or not the point passed in as parameter is equal to this - * note that if px passed in is null, returns false - * @type bool - */ + /** + * APIMethod: equals + * Determine whether one pixel is equivalent to another + * + * Parameters: + * px - {} + * + * Return: + * {Boolean} The point passed in as parameter is equal to this. Note that + * if px passed in is null, returns false. + */ equals:function(px) { var equals = false; if (px != null) { @@ -110,23 +155,29 @@ OpenLayers.Pixel.prototype = { }, /** - * @param {int} x - * @param {int} y - * - * @return a new Pixel with this pixel's x&y augmented by the - * values passed in. - * @type OpenLayers.Pixel - */ + * APIMethod: add + * + * Parameters: + * x - {Integer} + * y - {Integer} + * + * Return: + * {} A new Pixel with this pixel's x&y augmented by the + * values passed in. + */ add:function(x, y) { return new OpenLayers.Pixel(this.x + x, this.y + y); }, /** - * @param {OpenLayers.Pixel} px + * APIMethod: offset * - * @return a new Pixel with this pixel's x&y augmented by the - * x&y values of the pixel passed in. - * @type OpenLayers.Pixel + * Parameters + * px - {} + * + * Return: + * {} A new Pixel with this pixel's x&y augmented by the + * x&y values of the pixel passed in. */ offset:function(px) { var newPx = this.clone(); @@ -149,56 +200,75 @@ OpenLayers.Pixel.prototype = { /** -* @class -* -* This class represents a width and height pair -*/ + * Class: OpenLayers.Size + * Instances of this class represent a width/height pair + */ OpenLayers.Size = OpenLayers.Class.create(); OpenLayers.Size.prototype = { - /** @type float */ + /** + * APIProperty: w + * {Number} width + */ w: 0.0, - /** @type float */ + /** + * APIProperty: h + * {Number} height + */ h: 0.0, - /** - * @constructor - * - * @param {float} w - * @param {float} h - */ + /** + * Constructor: OpenLayers.Size + * Create an instance of OpenLayers.Size + * + * Parameters: + * w - {Number} width + * h - {Number} height + */ initialize: function(w, h) { this.w = parseFloat(w); this.h = parseFloat(h); }, - /** - * @return String representation of OpenLayers.Size object. - * (ex. "w=55,h=66") - * @type String - */ + /** + * Method: toString + * Return the string representation of a size object + * + * Return: + * {String} The string representation of OpenLayers.Size object. + * (ex. "w=55,h=66") + */ toString:function() { return ("w=" + this.w + ",h=" + this.h); }, - /** - * @return New OpenLayers.Size object with the same w and h values - * @type OpenLayers.Size + /** + * APIMethod: clone + * Create a clone of this size object + * + * Return: + * {} A new OpenLayers.Size object with the same w and h + * values */ clone:function() { return new OpenLayers.Size(this.w, this.h); }, - /** - * @param {OpenLayers.Size} sz - * @returns Boolean value indicating whether the passed-in OpenLayers.Size - * object has the same w and h components as this - * note that if sz passed in is null, returns false - * - * @type bool - */ + /** + * + * APIMethod: equals + * Determine where this size is equal to another + * + * Parameters: + * sz - {} + * + * Return: + * {Boolean} The passed in size has the same h and w properties as this one. + * Note that if sz passed in is null, returns false. + * + */ equals:function(sz) { var equals = false; if (sz != null) { @@ -220,76 +290,98 @@ OpenLayers.Size.prototype = { /** -* @class -* -* This class represents a longitude and latitude pair -*/ + * Class: OpenLayers.LonLat + * This class represents a longitude and latitude pair + */ OpenLayers.LonLat = OpenLayers.Class.create(); OpenLayers.LonLat.prototype = { - /** @type float */ + /** + * APIProperty: lon + * {Float} + */ lon: 0.0, - /** @type float */ + /** + * APIProperty: lat + * {Float} + */ lat: 0.0, /** - * @constructor - * - * @param {float} lon - * @param {float} lat - */ + * Constructor: OpenLayers.LonLat + * Create a new OpenLayers.LonLat instance + * + * Parameters: + * lon - {Number} The lon coordinate + * lat - {Number} The lat coordinate + */ initialize: function(lon, lat) { this.lon = parseFloat(lon); this.lat = parseFloat(lat); }, - /** - * @return String representation of OpenLayers.LonLat object. - * (ex. "lon=5,lat=42") - * @type String - */ + /** + * Method: toString + * Return a readable string version of the lonlat + * + * Return: + * {String} String representation of OpenLayers.LonLat object. + * (ex. "lon=5,lat=42") + */ toString:function() { return ("lon=" + this.lon + ",lat=" + this.lat); }, /** - * @return Shortened String representation of OpenLayers.LonLat object. - * (ex. "5, 42") - * @type String - */ + * APIMethod: toShortString + * + * Return: + * {String} Shortened String representation of OpenLayers.LonLat object. + * (ex. "5, 42") + */ toShortString:function() { return (this.lon + ", " + this.lat); }, /** - * @return New OpenLayers.LonLat object with the same lon and lat values - * @type OpenLayers.LonLat + * APIMethod: clone + * + * Return: + * {} New OpenLayers.LonLat object with the same lon + * and lat values */ clone:function() { return new OpenLayers.LonLat(this.lon, this.lat); }, /** - * @param {float} lon - * @param {float} lat - * - * @return A new OpenLayers.LonLat object with the lon and lat passed-in - * added to this's. - * @type OpenLayers.LonLat - */ + * APIMethod: add + * + * Parameters: + * lon - {Float} + * lat - {Float} + * + * Return: + * {} A new OpenLayers.LonLat object with the lon and + * lat passed-in added to this's. + */ add:function(lon, lat) { return new OpenLayers.LonLat(this.lon + lon, this.lat + lat); }, /** - * @param {OpenLayers.LonLat} ll - * @returns Boolean value indicating whether the passed-in OpenLayers.LonLat - * object has the same lon and lat components as this - * note that if ll passed in is null, returns false - * - * @type bool - */ + * APIMethod: equals + * + * Parameters: + * ll - {} + * + * Return: + * {Boolean} Boolean value indicating whether the passed-in + * object has the same lon and lat + * components as this. + * Note: if ll passed in is null, returns false + */ equals:function(ll) { var equals = false; if (ll != null) { @@ -300,11 +392,15 @@ OpenLayers.LonLat.prototype = { }, /** - * @param {OpenLayers.Bounds} maxExtent + * APIMethod: wrapDateLine * - * @returns A copy of this lonlat, but wrapped around the "dateline" (as - * specified by the borders of maxExtent) - * @type OpenLayers.LonLat + * Parameters: + * maxExtent - {} + * + * Return: + * {} A copy of this lonlat, but wrapped around the + * "dateline" (as specified by the borders of + * maxExtent) */ wrapDateLine: function(maxExtent) { @@ -329,17 +425,19 @@ OpenLayers.LonLat.prototype = { CLASS_NAME: "OpenLayers.LonLat" }; -/** Alternative constructor that builds a new OpenLayers.LonLat from a -* parameter string -* -* @constructor -* -* @param {String} str Comma-separated Lon,Lat coordinate string. -* (ex. "5,40") -* -* @returns New OpenLayers.LonLat object built from the passed-in String. -* @type OpenLayers.LonLat -*/ +/** + * Function: fromString + * Alternative constructor that builds a new from a + * parameter string + * + * Parameters: + * str - {String} Comma-separated Lon,Lat coordinate string. + * (ex. "5,40") + * + * Return: + * {} New object built from the + * passed-in String. + */ OpenLayers.LonLat.fromString = function(str) { var pair = str.split(","); return new OpenLayers.LonLat(parseFloat(pair[0]), @@ -358,35 +456,49 @@ OpenLayers.LonLat.fromString = function(str) { /** -* @class -* -* This class represents a bounding box. -* Data stored as left, bottom, right, top floats -*/ + * Class: OpenLayers.Bounds + * Instances of this class represent bounding boxes. Data stored as left, + * bottom, right, top floats + */ OpenLayers.Bounds = OpenLayers.Class.create(); OpenLayers.Bounds.prototype = { - /** @type float */ + /** + * Property: left + * {Number} + */ left: 0.0, - /** @type float */ + /** + * Property: bottom + * {Number} + */ bottom: 0.0, - /** @type float */ + /** + * Property: right + * {Number} + */ right: 0.0, - /** @type float */ + /** + * Property: top + * {Number} + */ top: 0.0, /** - * @constructor - * - * @param {float} left - * @param {float} bottom - * @param {float} right - * @param {float} top - * - */ + * Constructor: OpenLayers.Bounds + * Construct a new bounds object. + * + * Parameters: + * left - {Number} The left bounds of the box. Note that for width + * calculations, this is assumed to be less than the right value. + * bottom - {Number} The bottom bounds of the box. Note that for height + * calculations, this is assumed to be more than the top value. + * right - {Number} The right bounds. + * top - {Number} The top bounds. + */ initialize: function(left, bottom, right, top) { this.left = parseFloat(left); this.bottom = parseFloat(bottom); @@ -395,22 +507,29 @@ OpenLayers.Bounds.prototype = { }, /** - * @returns A fresh copy of the bounds - * @type OpenLayers.Bounds + * Method: clone + * Create a cloned instance of this bounds. + * + * Return: + * {} A fresh copy of the bounds */ clone:function() { return new OpenLayers.Bounds(this.left, this.bottom, this.right, this.top); }, - /** - * @param {OpenLayers.Bounds} bounds - * @returns Boolean value indicating whether the passed-in OpenLayers.Bounds - * object has the same left, right, top, bottom components as this - * note that if bounds passed in is null, returns false - * - * @type bool - */ + /** + * Method: equals + * Test a two bounds for equivalence + * + * Parameters: + * bounds - {} + * + * Return: + * {Boolean} The passed-in OpenLayers.Bounds object has the same left, + * right, top, bottom components as this. Note that if bounds + * passed in is null, returns false. + */ equals:function(bounds) { var equals = false; if (bounds != null) { @@ -423,22 +542,27 @@ OpenLayers.Bounds.prototype = { }, /** - * @return String representation of OpenLayers.Bounds object. - * (ex."left-bottom=(5,42) right-top=(10,45)") - * @type String - */ + * APIMethod: toString + * + * Return: + * {String} String representation of OpenLayers.Bounds object. + * (ex."left-bottom=(5,42) right-top=(10,45)") + */ toString:function() { return ( "left-bottom=(" + this.left + "," + this.bottom + ")" + " right-top=(" + this.right + "," + this.top + ")" ); }, /** - * @param {int} decimal How many significant digits in the bbox coords? - * Default is 6 + * APIMethod: toBBOX * - * @returns Simple String representation of OpenLayers.Bounds object. - * (ex. "5,42,10,45") - * @type String + * Parameters: + * decimal - {Integer} How many significant digits in the bbox coords? + * Default is 6 + * + * Return: + * {String} Simple String representation of OpenLayers.Bounds object. + * (ex. "5,42,10,45") */ toBBOX:function(decimal) { if (decimal== null) { @@ -454,66 +578,84 @@ OpenLayers.Bounds.prototype = { }, /** - * @returns The width of the bounds - * @type float - */ + * APIMethod: getWidth + * + * Return: + * {Float} The width of the bounds + */ getWidth:function() { return (this.right - this.left); }, /** - * @returns The height of the bounds - * @type float - */ + * APIMethod: getHeight + * + * Return: + * {Float} The height of the bounds + */ getHeight:function() { return (this.top - this.bottom); }, /** - * @returns An OpenLayers.Size which represents the size of the box - * @type OpenLayers.Size - */ + * APIMethod: getSize + * + * Return: + * {} An which represents the size of the box + */ getSize:function() { return new OpenLayers.Size(this.getWidth(), this.getHeight()); }, /** - * @returns An OpenLayers.Pixel which represents the center of the bounds - * @type OpenLayers.Pixel - */ + * APIMethod: getCenterPixel + * + * Return: + * {} An which represents the center + * of the bounds + */ getCenterPixel:function() { return new OpenLayers.Pixel( (this.left + this.right) / 2, (this.bottom + this.top) / 2); }, /** - * @returns An OpenLayers.LonLat which represents the center of the bounds - * @type OpenLayers.LonLat - */ + * APIMethod: getCenterLonLat + * + * Return: + * {} An which represents the center + * of the bounds + */ getCenterLonLat:function() { return new OpenLayers.LonLat( (this.left + this.right) / 2, (this.bottom + this.top) / 2); }, /** - * @param {float} x - * @param {float} y - * - * @returns A new OpenLayers.Bounds whose coordinates are the same as this, - * but shifted by the passed-in x and y values - * @type OpenLayers.Bounds - */ + * APIMethod: add + * + * Parameters: + * x - {Float} + * y - {Float} + * + * Return: + * {} A new whose coordinates are + * the same as this, but shifted by the passed-in + * x and y values + */ add:function(x, y) { return new OpenLayers.Bounds(this.left + x, this.bottom + y, this.right + x, this.top + y); }, /** + * APIMethod: extend * Extend the bounds to include the point, lonlat, or bounds specified. + * Note: This function assumes that left} + * inclusive - {Boolean} Whether or not to include the border. + * Default is true. * - * @return Whether or not the passed-in lonlat is within this bounds - * @type Boolean + * Return: + * {Boolean} Whether or not the passed-in lonlat is within this bounds. */ containsLonLat:function(ll, inclusive) { return this.contains(ll.lon, ll.lat, inclusive); }, /** - * @param {OpenLayers.Pixel} px - * @param {Boolean} inclusive Whether or not to include the border. - * Default is true + * APIMethod: containsPixel + * + * Parameters: + * px - {} + * inclusive - {Boolean} Whether or not to include the border. + * Default is true. * - * @return Whether or not the passed-in pixel is within this bounds - * @type Boolean + * Return: + * {Boolean} Whether or not the passed-in pixel is within this bounds. */ containsPixel:function(px, inclusive) { return this.contains(px.x, px.y, inclusive); }, /** - * @param {float} x - * @param {float} y - * @param {Boolean} inclusive Whether or not to include the border. - * Default is true - * - * @return Whether or not the passed-in coordinates are within this bounds - * @type Boolean - */ + * APIMethod: contains + * + * Parameters: + * x - {Float} + * y - {Float} + * inclusive - {Boolean} Whether or not to include the border. + * Default is true. + * + * Return: + * {Boolean} Whether or not the passed-in coordinates are within this + * bounds. + */ contains:function(x, y, inclusive) { //set default @@ -598,14 +750,17 @@ OpenLayers.Bounds.prototype = { }, /** - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} inclusive Whether or not to include the border. - * Default is true + * APIMethod: intersectsBounds + * + * Parameters: + * bounds - {} + * inclusive - {} Whether or not to include the border. + * Default is true. * - * @return Whether or not the passed-in OpenLayers.Bounds object intersects - * this bounds. Simple math just check if either contains the other, - * allowing for partial. - * @type Boolean + * Return: + * {Boolean} Whether or not the passed-in OpenLayers.Bounds object + * intersects this bounds. Simple math just check if either + * contains the other, allowing for partial. */ intersectsBounds:function(bounds, inclusive) { @@ -631,18 +786,20 @@ OpenLayers.Bounds.prototype = { }, /** - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} partial If true, only part of passed-in - * OpenLayers.Bounds needs be within this bounds. - * If false, the entire passed-in bounds must be - * within. Default is false - * @param {Boolean} inclusive Whether or not to include the border. - * Default is true - * - * @return Whether or not the passed-in OpenLayers.Bounds object is - * contained within this bounds. - * @type Boolean - */ + * APIMethod: containsBounds + * + * bounds - {} + * partial - {} If true, only part of passed-in + * needs be within this bounds. + * If false, the entire passed-in bounds must be + * within. Default is false + * inclusive - {} Whether or not to include the border. + * Default is true. + * + * Return: + * {Boolean} Whether or not the passed-in OpenLayers.Bounds object is + * contained within this bounds. + */ containsBounds:function(bounds, partial, inclusive) { //set defaults @@ -675,11 +832,14 @@ OpenLayers.Bounds.prototype = { }, /** - * @param {OpenLayers.LonLat} lonlat - * - * @returns The quadrant ("br" "tr" "tl" "bl") of the bounds in which - * the coordinate lies. - * @type String + * APIMethod: determineQuadrant + * + * Parameters: + * lonlat - {} + * + * Return: + * {String} The quadrant ("br" "tr" "tl" "bl") of the bounds in which + * the coordinate lies. */ determineQuadrant: function(lonlat) { @@ -693,22 +853,29 @@ OpenLayers.Bounds.prototype = { }, /** - * @param {OpenLayers.Bounds} maxExtent - * @param {Object} options - * @option {float} leftTolerance Allow for a margin of error with the - * 'left' value of this bound. - * Default is 0 - * @option {float} rightTolerance Allow for a margin of error with the - * 'right' value of this bound. - * Default is 0 + * APIMethod: wrapDateLine + * + * Parameters: + * maxExtent - {} + * options - {Object} Some possible options are: + * leftTolerance - {float} Allow for a margin of error + * with the 'left' value of this + * bound. + * Default is 0. + * rightTolerance - {float} Allow for a margin of error + * with the 'right' value of + * this bound. + * Default is 0. * - * @returns A copy of this bounds, but wrapped around the "dateline" (as - * specified by the borders of maxExtent). Note that this - * function only returns a different bounds value if this bounds - * is *entirely* outside of the maxExtent. If this bounds - * straddles the dateline (is part in/part out of maxExtent), - * the returned bounds will be merely a copy of this one. - * @type OpenLayers.Bounds + * Return: + * {} A copy of this bounds, but wrapped around the + * "dateline" (as specified by the borders of + * maxExtent). Note that this function only returns + * a different bounds value if this bounds is + * *entirely* outside of the maxExtent. If this + * bounds straddles the dateline (is part in/part + * out of maxExtent), the returned bounds will be + * merely a copy of this one. */ wrapDateLine: function(maxExtent, options) { options = options || new Object(); @@ -740,31 +907,35 @@ OpenLayers.Bounds.prototype = { CLASS_NAME: "OpenLayers.Bounds" }; -/** Alternative constructor that builds a new OpenLayers.Bounds from a -* parameter string -* -* @constructor -* -* @param {String} str Comma-separated bounds string. (ex. "5,42,10,45") -* -* @returns New OpenLayers.Bounds object built from the passed-in String. -* @type OpenLayers.Bounds -*/ +/** + * APIFunction: fromString + * Alternative constructor that builds a new OpenLayers.Bounds from a + * parameter string + * + * Parameters: + * str - {String}Comma-separated bounds string. (ex. "5,42,10,45") + * + * Return: + * {} New object built from the + * passed-in String. + */ OpenLayers.Bounds.fromString = function(str) { var bounds = str.split(","); return OpenLayers.Bounds.fromArray(bounds); }; -/** Alternative constructor that builds a new OpenLayers.Bounds -* from an array -* -* @constructor -* -* @param {Array} bbox Array of bounds values (ex. [5,42,10,45]) -* -* @returns New OpenLayers.Bounds object built from the passed-in Array. -* @type OpenLayers.Bounds -*/ +/** + * APIFunction: fromArray + * Alternative constructor that builds a new OpenLayers.Bounds + * from an array + * + * Parameters: + * bbox - {Array} Array of bounds values (ex. [5,42,10,45]) + * + * Return: + * {} New object built from the + * passed-in Array. + */ OpenLayers.Bounds.fromArray = function(bbox) { return new OpenLayers.Bounds(parseFloat(bbox[0]), parseFloat(bbox[1]), @@ -772,30 +943,36 @@ OpenLayers.Bounds.fromArray = function(bbox) { parseFloat(bbox[3])); }; -/** Alternative constructor that builds a new OpenLayers.Bounds -* from an OpenLayers.Size -* -* @constructor -* -* @param {OpenLayers.Size} size -* -* @returns New OpenLayers.Bounds object built with top and left set to 0 and -* bottom right taken from the passed-in OpenLayers.Size. -* @type OpenLayers.Bounds -*/ +/** + * APIFunction: fromSize + * Alternative constructor that builds a new OpenLayers.Bounds + * from a size + * + * Parameters: + * size - {} + * + * Return: + * {} New object built from the + * passed-in size. + */ OpenLayers.Bounds.fromSize = function(size) { return new OpenLayers.Bounds(0, size.h, size.w, 0); }; + /** - * @param {String} quadrant - * - * @returns The opposing quadrant ("br" "tr" "tl" "bl"). For Example, if - * you pass in "bl" it returns "tr", if you pass in "br" it - * returns "tl", etc. - * @type String + * Function: oppositeQuadrant + * Get the opposite quadrant for a given quadrant string. + * + * Parameters: + * quadrant - {String} two character quadrant shortstring + * + * Return: + * {String} The opposing quadrant ("br" "tr" "tl" "bl"). For Example, if + * you pass in "bl" it returns "tr", if you pass in "br" it + * returns "tl", etc. */ OpenLayers.Bounds.oppositeQuadrant = function(quadrant) { var opp = ""; @@ -813,80 +990,160 @@ OpenLayers.Bounds.oppositeQuadrant = function(quadrant) { * * *********************/ +/** + * Namespace: OpenLayers.Element + */ OpenLayers.Element = { - visible: function(element) { - return OpenLayers.Util.getElement(element).style.display != 'none'; - }, - toggle: function() { - for (var i = 0; i < arguments.length; i++) { - var element = OpenLayers.Util.getElement(arguments[i]); - OpenLayers.Element[OpenLayers.Element.visible(element) ? 'hide' : 'show'](element); + /** + * APIFunction: visible + * + * Parameters: + * element - {DOMElement} + * + * Return: + * {Boolean} Is the element visible? + */ + visible: function(element) { + return OpenLayers.Util.getElement(element).style.display != 'none'; + }, + + /** + * APIFunction: toggle + * Toggle the visibility of element(s) passed in + * + * Parameters: + * element - {DOMElement} Actually user can pass any number of elements + */ + toggle: function() { + for (var i = 0; i < arguments.length; i++) { + var element = OpenLayers.Util.getElement(arguments[i]); + var display = OpenLayers.Element.visible(element) ? 'hide' + : 'show'; + OpenLayers.Element[display](element); + } + }, + + + /** + * APIFunction: hide + * Hide element(s) passed in + * + * Parameters: + * element - {DOMElement} Actually user can pass any number of elements + */ + hide: function() { + for (var i = 0; i < arguments.length; i++) { + var element = OpenLayers.Util.getElement(arguments[i]); + element.style.display = 'none'; + } + }, + + /** + * APIFunction: show + * Show element(s) passed in + * + * Parameters: + * element - {DOMElement} Actually user can pass any number of elements + */ + show: function() { + for (var i = 0; i < arguments.length; i++) { + var element = OpenLayers.Util.getElement(arguments[i]); + element.style.display = ''; + } + }, + + /** + * APIFunction: remove + * Remove the specified element from the DOM. + * + * Parameters: + * element - {DOMElement} + */ + remove: function(element) { + element = OpenLayers.Util.getElement(element); + element.parentNode.removeChild(element); + }, + + /** + * APIFunction: getHeight + * + * Parameters: + * element - {DOMElement} + * + * Return: + * {Integer} The offset height of the element passed in + */ + getHeight: function(element) { + element = OpenLayers.Util.getElement(element); + return element.offsetHeight; + }, + + /** + * APIFunction: getDimensions + * + * Parameters: + * element - {DOMElement} + * + * Return: + * {Object} Object with 'width' and 'height' properties which are the + * dimensions of the element passed in. + */ + getDimensions: function(element) { + element = OpenLayers.Util.getElement(element); + if (OpenLayers.Element.getStyle(element, 'display') != 'none') { + return {width: element.offsetWidth, height: element.offsetHeight}; + } + + // All *Width and *Height properties give 0 on elements with display none, + // so enable the element temporarily + var els = element.style; + var originalVisibility = els.visibility; + var originalPosition = els.position; + els.visibility = 'hidden'; + els.position = 'absolute'; + els.display = ''; + var originalWidth = element.clientWidth; + var originalHeight = element.clientHeight; + els.display = 'none'; + els.position = originalPosition; + els.visibility = originalVisibility; + return {width: originalWidth, height: originalHeight}; + }, + + /** + * APIFunction: getStyle + * + * Parameters: + * element - {DOMElement} + * style - {?} + * + * Return: + * {?} + */ + getStyle: function(element, style) { + element = OpenLayers.Util.getElement(element); + var value = element.style[style.camelize()]; + if (!value) { + if (document.defaultView && + document.defaultView.getComputedStyle) { + + var css = document.defaultView.getComputedStyle(element, null); + value = css ? css.getPropertyValue(style) : null; + } else if (element.currentStyle) { + value = element.currentStyle[style.camelize()]; + } + } + + var positions = ['left', 'top', 'right', 'bottom']; + if (window.opera && + (OpenLayers.Util.indexOf(positions,style) != -1) && + (OpenLayers.Element.getStyle(element, 'position') == 'static')) { + value = 'auto'; + } + + return value == 'auto' ? null : value; } - }, - - hide: function() { - for (var i = 0; i < arguments.length; i++) { - var element = OpenLayers.Util.getElement(arguments[i]); - element.style.display = 'none'; - } - }, - - show: function() { - for (var i = 0; i < arguments.length; i++) { - var element = OpenLayers.Util.getElement(arguments[i]); - element.style.display = ''; - } - }, - - remove: function(element) { - element = OpenLayers.Util.getElement(element); - element.parentNode.removeChild(element); - }, - - getHeight: function(element) { - element = OpenLayers.Util.getElement(element); - return element.offsetHeight; - }, - - getDimensions: function(element) { - element = OpenLayers.Util.getElement(element); - if (OpenLayers.Element.getStyle(element, 'display') != 'none') - return {width: element.offsetWidth, height: element.offsetHeight}; - - // All *Width and *Height properties give 0 on elements with display none, - // so enable the element temporarily - var els = element.style; - var originalVisibility = els.visibility; - var originalPosition = els.position; - els.visibility = 'hidden'; - els.position = 'absolute'; - els.display = ''; - var originalWidth = element.clientWidth; - var originalHeight = element.clientHeight; - els.display = 'none'; - els.position = originalPosition; - els.visibility = originalVisibility; - return {width: originalWidth, height: originalHeight}; - }, - - getStyle: function(element, style) { - element = OpenLayers.Util.getElement(element); - var value = element.style[style.camelize()]; - if (!value) { - if (document.defaultView && document.defaultView.getComputedStyle) { - var css = document.defaultView.getComputedStyle(element, null); - value = css ? css.getPropertyValue(style) : null; - } else if (element.currentStyle) { - value = element.currentStyle[style.camelize()]; - } - } - - if (window.opera && OpenLayers.Util.indexOf(['left', 'top', 'right', 'bottom'],style) != -1) - if (OpenLayers.Element.getStyle(element, 'position') == 'static') value = 'auto'; - - return value == 'auto' ? null : value; - } }; @@ -896,31 +1153,40 @@ OpenLayers.Element = { * * *********************/ + /** -* @param {String} sStart -* -* @returns Whether or not this string starts with the string passed in. -* @type Boolean -*/ + * APIFunction: String.startsWith + * + * Parameters: + * sStart - {Sring} + * + * Return: + * {Boolean} Whether or not this string starts with the string passed in. + */ String.prototype.startsWith = function(sStart) { return (this.substr(0,sStart.length) == sStart); }; /** -* @param {String} str -* -* @returns Whether or not this string contains with the string passed in. -* @type Boolean -*/ + * APIFunction: String.contains + * + * Parameters: + * str - {String} + * + * Return: + * {Boolean} Whether or not this string contains with the string passed in. + */ String.prototype.contains = function(str) { return (this.indexOf(str) != -1); }; /** -* @returns A trimmed version of the string - all leading and -* trailing spaces removed -* @type String -*/ + * APIMethod: String.trim + * + * Return: + * {String} A trimmed version of the string - all leading and + * trailing spaces removed + */ String.prototype.trim = function() { var b = 0; @@ -936,13 +1202,27 @@ String.prototype.trim = function() { return this.substring(b, e+1); }; - +/** + * APIFunction: String.indexOf + * + * Parameters: + * object - {Object} Can be a string or a number + * + * Return: + * {Integer} The index of the encountered object, or -1 if not found. + */ String.indexOf = function(object) { for (var i = 0; i < this.length; i++) if (this[i] == object) return i; return -1; }; +/** + * APIFunction: camelize + * + * Return: + * {String} The string, camelized + */ String.prototype.camelize = function() { var oStringList = this.split('-'); if (oStringList.length == 1) return oStringList[0]; @@ -966,13 +1246,16 @@ String.prototype.camelize = function() { * * *********************/ -/** NOTE: Works only with integer values does *not* work with floats! +/** + * APIFunction: Number.limitSigDigs + * Works only with integer values does *not* work with floats! * - * @param {int} sig + * Parameters: + * sig - {Integer} * - * @returns The number, rounded to the specified number of significant digits. - * If null, 0, or negaive value passed in, returns 0 - * @type int + * Return: + * {Integer} The number, rounded to the specified number of significant digits. + * If null, 0, or negaive value passed in, returns 0 */ Number.prototype.limitSigDigs = function(sig) { var number = (sig > 0) ? this.toString() : 0; @@ -990,6 +1273,15 @@ Number.prototype.limitSigDigs = function(sig) { * * *********************/ +/** + * APIFunction: Function.bind + * + * Parameters: + * object - {Object} + * + * Return: + * {Function} + */ Function.prototype.bind = function() { var __method = this, args = [], object = arguments[0]; for (var i = 1; i < arguments.length; i++) @@ -1001,9 +1293,18 @@ Function.prototype.bind = function() { } }; +/** + * APIFunction: Function.bindAsEventListener + * + * Parameters: + * object - {Object} + * + * Return: + * {Function} + */ Function.prototype.bindAsEventListener = function(object) { var __method = this; return function(event) { return __method.call(object, event || window.event); } -}; +}; \ No newline at end of file diff --git a/lib/OpenLayers/Console.js b/lib/OpenLayers/Console.js index 62ed03394d..4f52ff0242 100644 --- a/lib/OpenLayers/Console.js +++ b/lib/OpenLayers/Console.js @@ -3,17 +3,18 @@ * for the full text of the license. */ /** + * Namespace: OpenLayers.Console * The OpenLayers.Console namespace is used for debugging and error logging. * If the Firebug Lite (../Firebug/firebug.js) is included before this script, * calls to OpenLayers.Console methods will get redirected to window.console. * This makes use of the Firebug extension where available and allows for * cross-browser debugging Firebug style. * + * Note: * Note that behavior will differ with the Firebug extention and Firebug Lite. * Most notably, the Firebug Lite console does not currently allow for * hyperlinks to code or for clicking on object to explore their properties. * - * @fileoverview Error logging and debugging console */ OpenLayers.Console = { /** @@ -24,6 +25,7 @@ OpenLayers.Console = { */ /** + * APIFunction: log * Log an object in the console. The Firebug Lite console logs string * representation of objects. Given multiple arguments, they will * be cast to strings and logged with a space delimiter. If the first @@ -31,86 +33,95 @@ OpenLayers.Console = { * will be used in string substitution. Any additional arguments (beyond * the number substituted in a format string) will be appended in a space- * delimited line. - * - * Examples: - * // Firebug Lite logs someObject.toString() - * OpenLayers.Console.log(someObject); * - * // string substitution - * OpenLayers.Console.log("%s jumped over %s", cow, moon); - * - * @param {Object} object + * Parameters: + * object - {Object} */ log: function() {}, /** + * APIFunction: debug * Writes a message to the console, including a hyperlink to the line * where it was called. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) object + * Parameters: + * object - {Object} */ debug: function() {}, /** + * APIFunction: info * Writes a message to the console with the visual "info" icon and color * coding and a hyperlink to the line where it was called. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) object + * Parameters: + * object - {Object} */ info: function() {}, /** + * APIFunction: warn * Writes a message to the console with the visual "warning" icon and * color coding and a hyperlink to the line where it was called. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) object + * Parameters: + * object - {Object} */ warn: function() {}, /** + * APIFunction: error * Writes a message to the console with the visual "error" icon and color * coding and a hyperlink to the line where it was called. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) object + * Parameters: + * object - {Object} */ error: function() {}, /** + * APIFunction: assert * Tests that an expression is true. If not, it will write a message to * the console and throw an exception. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) expression + * Parameters: + * object - {Object} */ assert: function() {}, /** + * APIFunction: dir * Prints an interactive listing of all properties of the object. This * looks identical to the view that you would see in the DOM tab. * - * @param (Object) object + * Parameters: + * object - {Object} */ dir: function() {}, /** + * APIFunction: dirxml * Prints the XML source tree of an HTML or XML element. This looks * identical to the view that you would see in the HTML tab. You can click * on any node to inspect it in the HTML tab. * - * @param (Object) object + * Parameters: + * object - {Object} */ dirxml: function() {}, /** + * APIFunction: trace * Prints an interactive stack trace of JavaScript execution at the point * where it is called. The stack trace details the functions on the stack, * as well as the values that were passed as arguments to each function. @@ -121,28 +132,33 @@ OpenLayers.Console = { trace: function() {}, /** + * APIFunction: group * Writes a message to the console and opens a nested block to indent all * future messages sent to the console. Call OpenLayers.Console.groupEnd() * to close the block. * * May be called with multiple arguments as with OpenLayers.Console.log(). * - * @param (Object) object + * Parameters: + * object - {Object} */ group: function() {}, /** + * APIFunction: groupEnd * Closes the most recently opened block created by a call to * OpenLayers.Console.group */ groupEnd: function() {}, /** + * APIFunction: time * Creates a new timer under the given name. Call * OpenLayers.Console.timeEnd(name) * with the same name to stop the timer and print the time elapsed. * - * @param {String} name + * Parameters: + * name - {String} */ time: function() {}, @@ -150,7 +166,8 @@ OpenLayers.Console = { * Stops a timer created by a call to OpenLayers.Console.time(name) and * writes the time elapsed. * - * @param {String} name + * Parameters: + * name - {String} */ timeEnd: function() {}, @@ -160,7 +177,8 @@ OpenLayers.Console = { * * This function is not currently implemented in Firebug Lite. * - * @param {String} title Optional title for the profiler + * Parameters: + * title - {String} Optional title for the profiler */ profile: function() {}, @@ -178,11 +196,14 @@ OpenLayers.Console = { * * This function is not currently implemented in Firebug Lite. * - * @param {String} title Optional title to be printed with count + * Parameters: + * title - {String} Optional title to be printed with count */ count: function() {}, - /** @final @type String */ + /** + * Constant: CLASS_NAME + */ CLASS_NAME: "OpenLayers.Console" }; diff --git a/lib/OpenLayers/Control.js b/lib/OpenLayers/Control.js index d55be78bc7..585ef311f3 100644 --- a/lib/OpenLayers/Control.js +++ b/lib/OpenLayers/Control.js @@ -3,7 +3,9 @@ * for the full text of the license. */ /** -* @class +* Class: OpenLayers.Control +* Controls affect the display or behavior of the map. They allow everything +* from panning and zooming to displaying a scale indicator. */ OpenLayers.Control = OpenLayers.Class.create(); @@ -13,40 +15,58 @@ OpenLayers.Control.TYPE_TOOL = 3; OpenLayers.Control.prototype = { - /** @type String */ - id: null, + /** + * Property: id + * {String} + */ + id: null, - /** this gets set in the addControl() function in OpenLayers.Map - * @type OpenLayers.Map */ - map: null, - - /** @type DOMElement */ - div: null, + /** + * Property: map + * {} this gets set in the addControl() function in + * OpenLayers.Map + */ + map: null, /** - * Controls can have a 'type'. The type determines the type of interactions - * which are possible with them when they are placed into a toolbar. - * - * @type OpenLayers.Control.TYPES - */ - type: null, + * Property: div + * {DOMElement} + */ + div: null, - /** This property is used for CSS related to the drawing of the Control. - * - * @type string - */ - displayClass: "", + /** + * Property: type + * {OpenLayers.Control.TYPES} Controls can have a 'type'. The type + * determines the type of interactions which are possible with them when + * they are placed into a toolbar. + */ + type: null, - /** @type boolean */ - active: null, + /** + * Property: displayClass + * {string} This property is used for CSS related to the drawing of the + * Control. + */ + displayClass: "", - /** @type OpenLayers.Handler */ - handler: null, + /** + * Property: active + * {boolean} null + */ + active: null, + + /** + * Property: handler + * { null + */ + handler: null, /** - * @constructor + * Constructor: OpenLayers.Control + * Create an OpenLayers Control. * - * @param {Object} options + * Parameters: + * options - {Object} */ initialize: function (options) { // We do this before the extend so that instances can override @@ -60,7 +80,7 @@ OpenLayers.Control.prototype = { }, /** - * + * Method: destroy */ destroy: function () { // eliminate circular references @@ -70,11 +90,14 @@ OpenLayers.Control.prototype = { this.map = null; }, - /** Set the map property for the control. This is done through an accessor + /** + * Method: setMap + * Set the map property for the control. This is done through an accessor * so that subclasses can override this and take special action once * they have their map variable set. - * - * @param {OpenLayers.Map} map + * + * Parameters: + * map - {} */ setMap: function(map) { this.map = map; @@ -84,10 +107,13 @@ OpenLayers.Control.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: draw * - * @returns A reference to the DIV DOMElement containing the control - * @type DOMElement + * Parameters: + * px - {} + * + * Return: + * {DOMElement} A reference to the DIV DOMElement containing the control */ draw: function (px) { if (this.div == null) { @@ -103,7 +129,10 @@ OpenLayers.Control.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: moveTo + * + * Parameters: + * px - {} */ moveTo: function (px) { if ((px != null) && (this.div != null)) { @@ -113,7 +142,10 @@ OpenLayers.Control.prototype = { }, /** - * @type boolean + * Method: activate + * + * Return: + * {Boolean} */ activate: function () { if (this.active) { @@ -127,7 +159,10 @@ OpenLayers.Control.prototype = { }, /** - * @type boolean + * Method: deactivate + * + * Return: + * {Boolean} */ deactivate: function () { if (this.active) { diff --git a/lib/OpenLayers/Control/ArgParser.js b/lib/OpenLayers/Control/ArgParser.js index e54d9936ee..02edc9b898 100644 --- a/lib/OpenLayers/Control/ArgParser.js +++ b/lib/OpenLayers/Control/ArgParser.js @@ -1,38 +1,54 @@ -/* Copyright (c) 2006 MetaCarta, Inc., published under a modified BSD license. +/* Cpyright (c) 2006 MetaCarta, Inc., published under a modified BSD license. * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.ArgParser + * + * Inherits from: + * - */ OpenLayers.Control.ArgParser = OpenLayers.Class.create(); OpenLayers.Control.ArgParser.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type OpenLayers.LonLat */ + /** + * Parameter: center + * {} + */ center: null, - /** @type int */ + /** + * Parameter: zoom + * {int} + */ zoom: null, - /** @type Array */ + /** + * Parameter: layers + * {Array} + */ layers: null, /** - * @constructor - * - * @param {Object} options + * Constructor: OpenLayers.Control.ArgParser + * + * Parameters: + * options - {Object} */ initialize: function(options) { OpenLayers.Control.prototype.initialize.apply(this, arguments); }, - /** Set the map property for the control. + /** + * Method: setMap + * Set the map property for the control. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Control.prototype.setMap.apply(this, arguments); @@ -72,7 +88,9 @@ OpenLayers.Control.ArgParser.prototype = } }, - /** As soon as a baseLayer has been loaded, we center and zoom + /** + * Method: setCenter + * As soon as a baseLayer has been loaded, we center and zoom * ...and remove the handler. */ setCenter: function() { @@ -86,7 +104,9 @@ OpenLayers.Control.ArgParser.prototype = } }, - /** As soon as all the layers are loaded, cycle through them and + /** + * Method: configureLayers + * As soon as all the layers are loaded, cycle through them and * hide or show them. */ configureLayers: function() { diff --git a/lib/OpenLayers/Control/DragPan.js b/lib/OpenLayers/Control/DragPan.js index 0cb876a268..9cdb3d2077 100644 --- a/lib/OpenLayers/Control/DragPan.js +++ b/lib/OpenLayers/Control/DragPan.js @@ -3,19 +3,29 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control.js * @requires OpenLayers/Handler/Drag.js + * + * Class: OpenLayers.Control.DragPan + * DragPan control. + * + * Inherits from: + * - */ OpenLayers.Control.DragPan = OpenLayers.Class.create(); OpenLayers.Control.DragPan.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type OpenLayers.Control.TYPES */ + + /** + * Property: type + * {OpenLayers.Control.TYPES} + */ type: OpenLayers.Control.TYPE_TOOL, /** - * + * Method: draw + * Creates a Drag handler, using and + * as callbacks. */ draw: function() { this.handler = new OpenLayers.Handler.Drag( this, @@ -23,7 +33,10 @@ OpenLayers.Control.DragPan.prototype = }, /** - * @param {OpenLayers.Pixel} xy Pixel of the up position + * Method: panMap + * + * Parameters: + * xy - {} Pixel of the up position */ panMap: function (xy) { var deltaX = this.handler.start.x - xy.x; @@ -39,7 +52,10 @@ OpenLayers.Control.DragPan.prototype = }, /** - * @param {OpenLayers.Pixel} xy Pixel of the up position + * Method: panMapDone + * + * Parameters: + * xy - {} Pixel of the up position */ panMapDone: function (xy) { var deltaX = this.handler.start.x - xy.x; diff --git a/lib/OpenLayers/Control/DrawFeature.js b/lib/OpenLayers/Control/DrawFeature.js index da4b8dfb26..194febfaf5 100644 --- a/lib/OpenLayers/Control/DrawFeature.js +++ b/lib/OpenLayers/Control/DrawFeature.js @@ -4,42 +4,50 @@ /** - * Draws features on a vector layer when active. - * - * @class * @requires OpenLayers/Control.js * @requires OpenLayers/Feature/Vector.js + * + * Class: OpenLayers.Control.DrawFeature + * Draws features on a vector layer when active. + * + * Inherits from: + * - */ OpenLayers.Control.DrawFeature = OpenLayers.Class.create(); OpenLayers.Control.DrawFeature.prototype = OpenLayers.Class.inherit(OpenLayers.Control, { /** - * @type OpenLayers.Layer.Vector + * Property: layer + * {} */ layer: null, /** - * @type {Object} The functions that are sent to the handler for callback + * Property: callbacks + * {Object} The functions that are sent to the handler for callback */ callbacks: null, /** - * @type {Function} Called after each feature is added + * APIProperty: featureAdded + * {Function} Called after each feature is added */ featureAdded: function() {}, /** - * Used to set non-default properties on the control's handler - * - * @type Object + * APIProperty: handlerOptions + * {Object} Used to set non-default properties on the control's handler */ handlerOptions: null, /** - * @param {OpenLayers.Layer.Vector} layer - * @param {OpenLayers.Handler} handler - * @param {Object} options + * Constructor: OpenLayers.Control.DrawFeature + * + * Parameters: + * layer - {} + * handler - {} + * options - {Object} */ initialize: function(layer, handler, options) { OpenLayers.Control.prototype.initialize.apply(this, [options]); @@ -50,7 +58,7 @@ OpenLayers.Control.DrawFeature.prototype = }, /** - * + * Method: drawFeature */ drawFeature: function(geometry) { var feature = new OpenLayers.Feature.Vector(geometry); diff --git a/lib/OpenLayers/Control/EditingToolbar.js b/lib/OpenLayers/Control/EditingToolbar.js index 74723e6de0..dbc8ff4a0d 100644 --- a/lib/OpenLayers/Control/EditingToolbar.js +++ b/lib/OpenLayers/Control/EditingToolbar.js @@ -3,20 +3,24 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control/Panel.js * @requires OpenLayers/Control/Navigation.js * @requires OpenLayers/Control/DrawFeature.js + * + * Class: OpenLayers.Control.EditingToolbar + */ OpenLayers.Control.EditingToolbar = OpenLayers.Class.create(); OpenLayers.Control.EditingToolbar.prototype = OpenLayers.Class.inherit( OpenLayers.Control.Panel, { /** + * Constructor: OpenLayers.Control.EditingToolbar * Create an editing toolbar for a given layer. - * @param {OpenLayers.Layer.Vector} layer - * @param {Object} options + * + * Parameters: + * layer - {} + * options - {Object} */ initialize: function(layer, options) { OpenLayers.Control.Panel.prototype.initialize.apply(this, [options]); @@ -36,6 +40,7 @@ OpenLayers.Control.EditingToolbar.prototype = }, /** + * Method: draw * calls the default draw, and then activates mouse defaults. */ draw: function() { diff --git a/lib/OpenLayers/Control/KeyboardDefaults.js b/lib/OpenLayers/Control/KeyboardDefaults.js index 86d610a0a8..b21562dbc2 100644 --- a/lib/OpenLayers/Control/KeyboardDefaults.js +++ b/lib/OpenLayers/Control/KeyboardDefaults.js @@ -4,27 +4,33 @@ /** - * @class - * * @requires OpenLayers/Control.js * @requires OpenLayers/Handler/Keyboard.js + * + * Class: OpenLayers.Control.KeyboardDefaults + * + * Inherits from: + * - */ OpenLayers.Control.KeyboardDefaults = OpenLayers.Class.create(); OpenLayers.Control.KeyboardDefaults.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type int */ + /** + * APIProperty: slideFactor + * Pixels to slide by. + */ slideFactor: 75, /** - * @constructor + * Constructor: OpenLayers.Control.KeyboardDefaults */ initialize: function() { OpenLayers.Control.prototype.initialize.apply(this, arguments); }, /** - * + * APIMethod: destroy */ destroy: function() { if (this.handler) { @@ -36,7 +42,8 @@ OpenLayers.Control.KeyboardDefaults.prototype = }, /** - * + * Method: draw + * Create handler. */ draw: function() { this.handler = new OpenLayers.Handler.Keyboard( this, { @@ -45,8 +52,11 @@ OpenLayers.Control.KeyboardDefaults.prototype = }, /** - * @param {Integer} code - */ + * Method: defaultKeyPress + * + * Parameters: + * code - {Integer} + */ defaultKeyPress: function (code) { switch(code) { case OpenLayers.Event.KEY_LEFT: diff --git a/lib/OpenLayers/Control/LayerSwitcher.js b/lib/OpenLayers/Control/LayerSwitcher.js index 4bd3930d6a..61df7e0e02 100644 --- a/lib/OpenLayers/Control/LayerSwitcher.js +++ b/lib/OpenLayers/Control/LayerSwitcher.js @@ -3,59 +3,93 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Control.js * - * @requires OpenLayers/Control.js - * @requires OpenLayers/Control.js + * Class: OpenLayers.Control.LayerSwitcher + * + * Inherits from: + * - */ OpenLayers.Control.LayerSwitcher = OpenLayers.Class.create(); OpenLayers.Control.LayerSwitcher.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type String */ + /** + * Property: activeColor + */ activeColor: "darkblue", // DOM Elements - /** @type DOMElement */ + /** + * Property: layersDiv + * {DOMElement} + */ layersDiv: null, - /** @type DOMElement */ + /** + * Property: baseLayersDiv + * {DOMElement} + */ baseLayersDiv: null, - /** @type Array */ + /** + * Property: baseLayers + * {Array} + */ baseLayers: null, - /** @type DOMElement */ + /** + * Property: dataLbl + * {DOMElement} + */ dataLbl: null, - /** @type DOMElement */ + /** + * Property: dataLayersDiv + * {DOMElement} + */ dataLayersDiv: null, - /** @type Array */ + /** + * Property: dataLayers + * {Array} + */ dataLayers: null, - /** @type DOMElement */ + /** + * Property: minimizeDiv + * {DOMElement} + */ minimizeDiv: null, - /** @type DOMElement */ + /** + * Property: maximizeDiv + * {DOMElement} + */ maximizeDiv: null, - /** @type Boolean */ + /** + * APIProperty: ascending + * {Boolean} + */ ascending: true, /** - * @constructor - */ + * Constructor: OpenLayers.Control.LayerSwitcher + * + * Parameters: + * options - {Object} + */ initialize: function(options) { OpenLayers.Control.prototype.initialize.apply(this, arguments); }, /** - * + * APIMethod: destroy */ destroy: function() { @@ -77,7 +111,10 @@ OpenLayers.Control.LayerSwitcher.prototype = }, /** - * @param {OpenLayers.Map} map + * Method: setMap + * + * Properties: + * map - {} */ setMap: function(map) { OpenLayers.Control.prototype.setMap.apply(this, arguments); @@ -89,8 +126,11 @@ OpenLayers.Control.LayerSwitcher.prototype = }, /** - * @returns A reference to the DIV DOMElement containing the switcher tabs - * @type DOMElement + * Method: draw + * + * Returns: + * {DOMElement} A reference to the DIV DOMElement containing the switcher + * tabs */ draw: function() { OpenLayers.Control.prototype.draw.apply(this); @@ -109,12 +149,13 @@ OpenLayers.Control.LayerSwitcher.prototype = return this.div; }, - /** user specifies either "base" or "data". we then clear all the - * corresponding listeners, the div, and reinitialize a new array. + /** + * Method: clearLayersArray + * user specifies either "base" or "data". we then clear all the + * corresponding listeners, the div, and reinitialize a new array. * - * @private - * - * @param {String} layersType Ei + * Parameters: + * layersType - {String} */ clearLayersArray: function(layersType) { var layers = this[layersType + "Layers"]; @@ -130,12 +171,14 @@ OpenLayers.Control.LayerSwitcher.prototype = }, - /** Goes through and takes the current state of the Map and rebuilds the - * control to display that state. Groups base layers into a radio-button - * group and lists each data layer with a checkbox. - * - * @returns A reference to the DIV DOMElement containing the control - * @type DOMElement + /** + * Method: redraw + * Goes through and takes the current state of the Map and rebuilds the + * control to display that state. Groups base layers into a radio-button + * group and lists each data layer with a checkbox. + * + * Returns: + * {DOMElement} A reference to the DIV DOMElement containing the control */ redraw: function() { @@ -219,16 +262,17 @@ OpenLayers.Control.LayerSwitcher.prototype = return this.div; }, - /** A label has been clicked, check or uncheck its corresponding input + /** + * Method: + * A label has been clicked, check or uncheck its corresponding input * - * @private - * - * @context - * {DOMElement} inputElem - * {OpenLayers.Control.LayerSwitcher} layerSwitcher - * {OpenLayers.Layer} layer - * - * @param {Event} e + * Parameters: + * e - {Event} + * + * Context: + * - {DOMElement} inputElem + * - {} layerSwitcher + * - {} layer */ onInputClick: function(e) { @@ -246,23 +290,24 @@ OpenLayers.Control.LayerSwitcher.prototype = OpenLayers.Event.stop(e); }, - /** Need to update the map accordingly whenever user clicks in either of - * the layers. + /** + * Method: + * Need to update the map accordingly whenever user clicks in either of + * the layers. * - * @private - * - * @param {Event} e + * Parameters: + * e - {Event} */ onLayerClick: function(e) { this.updateMap(); }, - /** Cycles through the loaded data and base layer input arrays and makes + /** + * Method: updateMap + * Cycles through the loaded data and base layer input arrays and makes * the necessary calls to the Map object such that that the map's * visual state corresponds to what the user has selected in the control - * - * @private */ updateMap: function() { @@ -282,9 +327,12 @@ OpenLayers.Control.LayerSwitcher.prototype = }, - /** Set up the labels and divs for the control + /** + * Method: maximizeControl + * Set up the labels and divs for the control * - * @param {Event} e + * Parameters: + * e - {Event} */ maximizeControl: function(e) { @@ -299,10 +347,13 @@ OpenLayers.Control.LayerSwitcher.prototype = } }, - /** Hide all the contents of the control, shrink the size, - * add the maximize icon - * - * @param {Event} e + /** + * Method: minimizeControl + * Hide all the contents of the control, shrink the size, + * add the maximize icon + * + * Parameters: + * e - {Event} */ minimizeControl: function(e) { @@ -316,12 +367,13 @@ OpenLayers.Control.LayerSwitcher.prototype = } }, - /** Hide/Show all LayerSwitcher controls depending on whether we are + /** + * Method: showControls + * Hide/Show all LayerSwitcher controls depending on whether we are * minimized or not * - * @private - * - * @param {Boolean} minimize + * Parameters: + * minimize - {Boolean} */ showControls: function(minimize) { @@ -331,8 +383,9 @@ OpenLayers.Control.LayerSwitcher.prototype = this.layersDiv.style.display = minimize ? "none" : ""; }, - /** Set up the labels and divs for the control - * + /** + * Method: loadContents + * Set up the labels and divs for the control */ loadContents: function() { @@ -460,33 +513,36 @@ OpenLayers.Control.LayerSwitcher.prototype = }, /** - * @private - * - * @param {Event} evt + * Method: ignoreEvent + * + * Parameters: + * evt - {Event} */ ignoreEvent: function(evt) { OpenLayers.Event.stop(evt); }, - /** Register a local 'mouseDown' flag so that we'll know whether or not + /** + * Method: mouseDown + * Register a local 'mouseDown' flag so that we'll know whether or not * to ignore a mouseUp event * - * @private - * - * @param {Event} evt + * Parameters: + * evt - {Event} */ mouseDown: function(evt) { this.mouseDown = true; this.ignoreEvent(evt); }, - /** If the 'mouseDown' flag has been set, that means that the drag was + /** + * Method: mouseUp + * If the 'mouseDown' flag has been set, that means that the drag was * started from within the LayerSwitcher control, and thus we can * ignore the mouseup. Otherwise, let the Event continue. * - * @private - * - * @param {Event} evt + * Parameters: + * evt - {Event} */ mouseUp: function(evt) { if (this.mouseDown) { diff --git a/lib/OpenLayers/Control/MouseDefaults.js b/lib/OpenLayers/Control/MouseDefaults.js index 3210009ef7..1838f5766d 100644 --- a/lib/OpenLayers/Control/MouseDefaults.js +++ b/lib/OpenLayers/Control/MouseDefaults.js @@ -3,9 +3,12 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.MouseDefaults + * + * Inherits from: + * - */ OpenLayers.Control.MouseDefaults = OpenLayers.Class.create(); OpenLayers.Control.MouseDefaults.prototype = @@ -15,21 +18,27 @@ OpenLayers.Control.MouseDefaults.prototype = This class is DEPRECATED in 2.4 and will be removed by 3.0. If you need this functionality, use Control.Navigation instead!!! */ - /** @type Boolean */ + /** + * Property: performedDrag + * {Boolean} + */ performedDrag: false, - /** @type function */ + /** + * Property: wheelObserver + * {Function} + */ wheelObserver: null, /** - * @constructor + * Constructor: OpenLayers.Control.MouseDefaults */ initialize: function() { OpenLayers.Control.prototype.initialize.apply(this, arguments); }, /** - * + * APIMethod: destroy */ destroy: function() { @@ -58,7 +67,7 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * + * Method: draw */ draw: function() { this.map.events.register( "click", this, this.defaultClick ); @@ -73,7 +82,7 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * + * Method: registerWheelEvents */ registerWheelEvents: function() { @@ -86,9 +95,13 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultClick * - * @type Boolean + * Parameters: + * evt - {Event} + * + * Returns: + * {Boolean} */ defaultClick: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -98,7 +111,10 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultDblClick + * + * Parameters: + * evt - {Event} */ defaultDblClick: function (evt) { var newCenter = this.map.getLonLatFromViewPortPx( evt.xy ); @@ -108,7 +124,10 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultMouseDown + * + * Parameters: + * evt - {Event} */ defaultMouseDown: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -134,7 +153,10 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultMouseMove + * + * Parameters: + * evt - {Event} */ defaultMouseMove: function (evt) { // record the mouse position, used in onWheelEvent @@ -168,7 +190,10 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultMouseUp + * + * Parameters: + * evt - {} */ defaultMouseUp: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -185,7 +210,10 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** - * @param {Event} evt + * Method: defaultMouseOut + * + * Parameters: + * evt - {Event} */ defaultMouseOut: function (evt) { if (this.mouseDragStart != null && @@ -198,7 +226,9 @@ OpenLayers.Control.MouseDefaults.prototype = }, - /** User spun scroll wheel up + /** + * Method: defaultWheelUp + * User spun scroll wheel up * */ defaultWheelUp: function(evt) { @@ -208,8 +238,9 @@ OpenLayers.Control.MouseDefaults.prototype = } }, - /** User spun scroll wheel down - * + /** + * Method: defaultWheelDown + * User spun scroll wheel down */ defaultWheelDown: function(evt) { if (this.map.getZoom() > 0) { @@ -218,8 +249,9 @@ OpenLayers.Control.MouseDefaults.prototype = } }, - /** Zoombox function. - * + /** + * Method: zoomBoxEnd + * Zoombox function. */ zoomBoxEnd: function(evt) { if (this.mouseDragStart != null) { @@ -245,6 +277,7 @@ OpenLayers.Control.MouseDefaults.prototype = }, /** + * Method: removeZoomBox * Remove the zoombox from the screen and nullify our reference to it. */ removeZoomBox: function() { @@ -258,9 +291,12 @@ OpenLayers.Control.MouseDefaults.prototype = */ - /** Catch the wheel event and handle it xbrowserly - * - * @param {Event} e + /** + * Method: onWheelEvent + * Catch the wheel event and handle it xbrowserly + * + * Parameters: + * e - {Event} */ onWheelEvent: function(e){ diff --git a/lib/OpenLayers/Control/MousePosition.js b/lib/OpenLayers/Control/MousePosition.js index 9d02c69ddd..af7a3a8329 100644 --- a/lib/OpenLayers/Control/MousePosition.js +++ b/lib/OpenLayers/Control/MousePosition.js @@ -4,46 +4,68 @@ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.MousePosition */ OpenLayers.Control.MousePosition = OpenLayers.Class.create(); OpenLayers.Control.MousePosition.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type DOMElement */ + /** + * Property: element + * {DOMElement} + */ element: null, - /** @type String */ + /** + * APIProperty: prefix + */ prefix: '', - /** @type String */ + /** + * APIProperty: seperator + * {String} + */ separator: ', ', - /** @type String */ + /** + * APIProperty: suffix + * {String} + */ suffix: '', - /** @type int */ + /** + * APIProperty: numDigits + * {Integer} + */ numdigits: 5, - /** @type int */ + /** + * APIProperty: granularity + * {Integer} + */ granularity: 10, - /** @type OpenLayers.LonLat */ + /** + * Property: lastXy + * {} + */ lastXy: null, /** - * @constructor + * Constructor: OpenLayers.Control.MousePosition * - * @param {DOMElement} options Options for control. + * Parameters: + * options - {DOMElement} Options for control. */ initialize: function(options) { OpenLayers.Control.prototype.initialize.apply(this, arguments); }, /** - * @type DOMElement + * Method: draw + * {DOMElement} */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); @@ -60,7 +82,7 @@ OpenLayers.Control.MousePosition.prototype = }, /** - * + * Method: redraw */ redraw: function(evt) { @@ -95,7 +117,7 @@ OpenLayers.Control.MousePosition.prototype = }, /** - * + * Method: setMap */ setMap: function() { OpenLayers.Control.prototype.setMap.apply(this, arguments); diff --git a/lib/OpenLayers/Control/MouseToolbar.js b/lib/OpenLayers/Control/MouseToolbar.js index 9c9f77a248..1e7db425e4 100644 --- a/lib/OpenLayers/Control/MouseToolbar.js +++ b/lib/OpenLayers/Control/MouseToolbar.js @@ -4,10 +4,12 @@ /** - * @class - * * @requires OpenLayers/Control.js * @requires OpenLayers/Control/MouseDefaults.js + * + * Class: OpenLayers.Control.MouseToolbar + * This class is DEPRECATED in 2.4 and will be removed by 3.0. + * If you need this functionality, use Control.NavToolbar instead!!! */ OpenLayers.Control.MouseToolbar = OpenLayers.Class.create(); OpenLayers.Control.MouseToolbar.X = 6; @@ -15,19 +17,34 @@ OpenLayers.Control.MouseToolbar.Y = 300; OpenLayers.Control.MouseToolbar.prototype = OpenLayers.Class.inherit( OpenLayers.Control.MouseDefaults, { - /** WARNING WARNING WARNING!!! - This class is DEPRECATED in 2.4 and will be removed by 3.0. - If you need this functionality, use Control.NavToolbar instead!!! */ - + /** + * Property: mode + */ mode: null, - + /** + * Property: buttons + */ buttons: null, - + + /** + * APIProperty: direction + * {String} 'vertical' or 'horizontal' + */ direction: "vertical", - /** @type String */ + /** + * Property: buttonClicked + * {String} + */ buttonClicked: null, + /** + * Constructor: OpenLayers.Control.MouseToolbar + * + * Parameters: + * position - {} + * direction - {String} + */ initialize: function(position, direction) { OpenLayers.Control.prototype.initialize.apply(this, arguments); this.position = new OpenLayers.Pixel(OpenLayers.Control.MouseToolbar.X, @@ -42,7 +59,7 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { for( var btnId in this.buttons) { @@ -54,6 +71,9 @@ OpenLayers.Control.MouseToolbar.prototype = arguments); }, + /** + * Method: draw + */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); OpenLayers.Control.MouseDefaults.prototype.draw.apply(this, arguments); @@ -68,7 +88,10 @@ OpenLayers.Control.MouseToolbar.prototype = return this.div; }, - + + /** + * Method: _addButton + */ _addButton:function(id, img, activeImg, xy, sz, title) { var imgLocation = OpenLayers.Util.getImagesLocation() + img; var activeImgLocation = OpenLayers.Util.getImagesLocation() + activeImg; @@ -97,7 +120,10 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt + * Method: buttonDown + * + * Parameters: + * evt - {Event} */ buttonDown: function(evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -106,7 +132,10 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt + * Method: buttonUp + * + * Parameters: + * evt - {Event} */ buttonUp: function(evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -120,8 +149,11 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt - */ + * Method: defaultDblClick + * + * Parameters: + * evt - {Event} + */ defaultDblClick: function (evt) { this.switchModeTo("pan"); this.performedDrag = false; @@ -132,8 +164,11 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt - */ + * Method: defaultMouseDown + * + * Parameters: + * evt - {Event} + */ defaultMouseDown: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; this.mouseDragStart = evt.xy.clone(); @@ -214,6 +249,12 @@ OpenLayers.Control.MouseToolbar.prototype = OpenLayers.Event.stop(evt); }, + /** + * Method: switchModeTo + * + * Parameters: + * mode - {String} + */ switchModeTo: function(mode) { if (mode != this.mode) { @@ -246,13 +287,19 @@ OpenLayers.Control.MouseToolbar.prototype = } }, + /** + * Method: leaveMode + */ leaveMode: function() { this.switchModeTo("pan"); }, /** - * @param {Event} evt - */ + * Method: defaultMouseMove + * + * Parameters: + * evt - {Event} + */ defaultMouseMove: function (evt) { if (this.mouseDragStart != null) { switch (this.mode) { @@ -283,8 +330,11 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt - */ + * Method: defaultMouseUp + * + * Parameters: + * evt - {Event} + */ defaultMouseUp: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; switch (this.mode) { @@ -303,8 +353,11 @@ OpenLayers.Control.MouseToolbar.prototype = }, /** - * @param {Event} evt - */ + * Method: defaultMouseOut + * + * Parameters: + * evt - {Event} + */ defaultMouseOut: function (evt) { if (this.mouseDragStart != null && OpenLayers.Util.mouseLeft(evt, this.map.div)) { @@ -317,6 +370,12 @@ OpenLayers.Control.MouseToolbar.prototype = } }, + /** + * Method: defaultClick + * + * Parameters: + * evt - {Event} + */ defaultClick: function (evt) { if (this.performedDrag) { this.performedDrag = false; diff --git a/lib/OpenLayers/Control/NavToolbar.js b/lib/OpenLayers/Control/NavToolbar.js index a701a4cdb3..d6e2870c39 100644 --- a/lib/OpenLayers/Control/NavToolbar.js +++ b/lib/OpenLayers/Control/NavToolbar.js @@ -3,17 +3,18 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control/Panel.js * @requires OpenLayers/Control/Navigation.js * @requires OpenLayers/Control/ZoomBox.js + * + * Class: OpenLayers.Control.NavToolbar */ OpenLayers.Control.NavToolbar = OpenLayers.Class.create(); OpenLayers.Control.NavToolbar.prototype = OpenLayers.Class.inherit( OpenLayers.Control.Panel, { /** + * Constructor: OpenLayers.Control.NavToolbar * Add our two mousedefaults controls. */ initialize: function(options) { @@ -25,6 +26,7 @@ OpenLayers.Control.NavToolbar.prototype = }, /** + * Method: draw * calls the default draw, and then activates mouse defaults. */ draw: function() { diff --git a/lib/OpenLayers/Control/Navigation.js b/lib/OpenLayers/Control/Navigation.js index ea927f3ecd..b301132887 100644 --- a/lib/OpenLayers/Control/Navigation.js +++ b/lib/OpenLayers/Control/Navigation.js @@ -3,25 +3,37 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control/ZoomBox.js * @requires OpenLayers/Control/DragPan.js * @requires OpenLayers/Handler/MouseWheel.js + * + * Class: OpenLayers.Control.Navigation */ OpenLayers.Control.Navigation = OpenLayers.Class.create(); OpenLayers.Control.Navigation.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type OpenLayers.Control.ZoomBox */ + /** + * Property: dragPan + * {} + */ dragPan: null, - /** @type OpenLayers.Control.ZoomBox */ + /** + * Property: zoomBox + * {} + */ zoomBox: null, - /** @type OpenLayers.Handler.MouseWheel */ + /** + * Property: wheelHandler + * {} + */ wheelHandler: null, + /** + * Method: activate + */ activate: function() { this.dragPan.activate(); this.wheelHandler.activate(); @@ -29,6 +41,9 @@ OpenLayers.Control.Navigation.prototype = return OpenLayers.Control.prototype.activate.apply(this,arguments); }, + /** + * Method: deactivate + */ deactivate: function() { this.zoomBox.deactivate(); this.dragPan.deactivate(); @@ -36,6 +51,9 @@ OpenLayers.Control.Navigation.prototype = return OpenLayers.Control.prototype.deactivate.apply(this,arguments); }, + /** + * Method: draw + */ draw: function() { this.map.events.register( "dblclick", this, this.defaultDblClick ); this.dragPan = new OpenLayers.Control.DragPan({map: this.map}); @@ -50,8 +68,11 @@ OpenLayers.Control.Navigation.prototype = }, /** - * @param {Event} evt - */ + * Method: defaultDblClick + * + * Parameters: + * evt - {Event} + */ defaultDblClick: function (evt) { var newCenter = this.map.getLonLatFromViewPortPx( evt.xy ); this.map.setCenter(newCenter, this.map.zoom + 1); @@ -59,6 +80,12 @@ OpenLayers.Control.Navigation.prototype = return false; }, + /** + * Method: wheelChange + * + * Parameters: + * evt - {Event} + */ wheelChange: function(evt, deltaZ) { var newZoom = this.map.getZoom() + deltaZ; if (!this.map.isValidZoomLevel(newZoom)) return; @@ -74,15 +101,23 @@ OpenLayers.Control.Navigation.prototype = this.map.setCenter( newCenter, newZoom ); }, - /** User spun scroll wheel up + /** + * Method: wheelUp + * User spun scroll wheel up * + * Parameters: + * evt - {Event} */ wheelUp: function(evt) { this.wheelChange(evt, 1); }, - /** User spun scroll wheel down + /** + * Method: wheelDown + * User spun scroll wheel down * + * Parameters: + * evt - {Event} */ wheelDown: function(evt) { this.wheelChange(evt, -1); diff --git a/lib/OpenLayers/Control/OverviewMap.js b/lib/OpenLayers/Control/OverviewMap.js index cc965d6c9f..c9fbe300f7 100644 --- a/lib/OpenLayers/Control/OverviewMap.js +++ b/lib/OpenLayers/Control/OverviewMap.js @@ -1,78 +1,88 @@ /* Copyright (c) 2006 MetaCarta, Inc., published under a modified BSD license. * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ -/** - * @fileoverview Locator Map Control - * @author Tim Schaub - */ /** - * @class - * * @requires OpenLayers/Control.js * @requires OpenLayers/BaseTypes.js * @requires OpenLayers/Events.js + * + * Class: OpenLayers.Control.OverviewMap + * Create an overview map to display the extent of your main map and provide + * additional navigation control. Create a new overview map with the + * constructor. + * + * Inerits from: + * - */ OpenLayers.Control.OverviewMap = OpenLayers.Class.create(); - OpenLayers.Control.OverviewMap.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** For div.id - * @type String */ + /** + * Property: id + * {String} For div.id + */ id: "OverviewMap", - /** @type DOMElement */ + /** + * Property: element + * {DOMElement} The DOM element that contains the overview map + */ element: null, /** - * The overvew map itself. - * @type OpenLayers.Map + * APIProperty: ovmap + * {} A reference to the overvew map itself. */ ovmap: null, /** - * The overvew map size in pixels. Note that this is the size of the map - * itself - the element that contains the map (default class name - * olControlOverviewMapElement) may have padding or other style attributes - * added via CSS. - * @type OpenLayers.Size + * APIProperty: size + * {} The overvew map size in pixels. Note that this is + * the size of the map itself - the element that contains the map (default + * class name olControlOverviewMapElement) may have padding or other style + * attributes added via CSS. */ size: new OpenLayers.Size(180, 90), /** - * Ordered list of layers in the overview map. If none are sent at - * construction, then the default below is used. - * - * @type Array(OpenLayers.Layer) + * APIProperty: layers + * {Array()} Ordered list of layers in the overview map. + * If none are sent at construction, the base layer for the main map is used. */ layers: null, /** - * The ratio of the overview map resolution to the main map resolution - * at which to zoom farther out on the overview map. - * @type Float + * APIProperty: minRatio + * {Numver} The ratio of the overview map resolution to the main map + * resolution at which to zoom farther out on the overview map. */ minRatio: 8, /** - * The ratio of the overview map resolution to the main map resolution - * at which to zoom farther in on the overview map. - * @type Float + * APIProperty: maxRatio + * {Float} The ratio of the overview map resolution to the main map + * resolution at which to zoom farther in on the overview map. */ maxRatio: 32, /** - * An object containing any non-default properties to be sent to the - * overview map's map constructor. These should include any non-default + * APIProperty: mapOptions + * {Object} An object containing any non-default properties to be sent to + * the overview map's map constructor. These should include any non-default * options that the main map was constructed with. - * @type: Object */ mapOptions: null, /** - * @constructor - * @param {Object} options Hashtable of options to set on the overview map + * Constructor: OpenLayers.Control.OverviewMap + * Create a new overview map + * + * Parameters: + * object - {Object} Properties of this object will be set on the overview + * map object. Note, to set options on the map object contained in this + * control, set as one of the options properties. */ initialize: function(options) { this.layers = new Array(); @@ -80,7 +90,8 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * + * APIMethod: destroy + * Deconstruct the control */ destroy: function() { if (!this.mapDiv) { // we've already been destroyed @@ -124,7 +135,8 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @type DOMElement + * Method: draw + * Render the control in the browser. */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); @@ -249,14 +261,22 @@ OpenLayers.Control.OverviewMap.prototype = return this.div; }, + /** + * Method: baseLayerDraw + * Draw the base layer - called if unable to complete in the initial draw + */ baseLayerDraw: function() { this.draw(); this.map.events.unregister("changebaselayer", this, this.baseLayerDraw); }, /** - * @param {OpenLayers.Event} evt - */ + * Method: rectMouseOut + * Handle browser events + * + * Parameters: + * evt - {} evt + */ rectMouseOut: function (evt) { if(this.rectDragStart != null) { if(this.performedRectDrag) { @@ -278,8 +298,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Event} evt - */ + * Method: rectMouseDown + * Handle browser events + * + * Parameters: + * evt - {} evt + */ rectMouseDown: function (evt) { if(!OpenLayers.Event.isLeftClick(evt)) return; this.rectDragStart = evt.xy.clone(); @@ -288,8 +312,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Event} evt - */ + * Method: rectMouseMove + * Handle browser events + * + * Parameters: + * evt - {} evt + */ rectMouseMove: function(evt) { if(this.rectDragStart != null) { var deltaX = this.rectDragStart.x - evt.xy.x; @@ -317,8 +345,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Event} evt - */ + * Method: rectMouseUp + * Handle browser events + * + * Parameters: + * evt - {} evt + */ rectMouseUp: function(evt) { if(!OpenLayers.Event.isLeftClick(evt)) return; if(this.performedRectDrag) { @@ -330,8 +362,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Event} evt - */ + * Method: rectDblClick + * Handle browser events + * + * Parameters: + * evt - {} evt + */ rectDblClick: function(evt) { this.performedRectDrag = false; OpenLayers.Event.stop(evt); @@ -339,8 +375,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Event} evt - */ + * Method: mapDivClick + * Handle browser events + * + * Parameters: + * evt - {} evt + */ mapDivClick: function(evt) { var pxBounds = this.getRectPxBounds(); var pxCenter = pxBounds.getCenterPixel(); @@ -362,9 +402,12 @@ OpenLayers.Control.OverviewMap.prototype = OpenLayers.Event.stop(evt); }, - /** Set up the labels and divs for the control - * - * @param {OpenLayers.Event} e + /** + * Method: maximizeControl + * Unhide the control. Called when the control is in the map viewport. + * + * Parameters: + * e - {} */ maximizeControl: function(e) { this.element.style.display = ''; @@ -374,10 +417,13 @@ OpenLayers.Control.OverviewMap.prototype = } }, - /** Hide all the contents of the control, shrink the size, - * add the maximize icon + /** + * Method: minimizeControl + * Hide all the contents of the control, shrink the size, + * add the maximize icon * - * @param {OpenLayers.Event} e + * Parameters: + * e - {} */ minimizeControl: function(e) { this.element.style.display = 'none'; @@ -387,12 +433,12 @@ OpenLayers.Control.OverviewMap.prototype = } }, - /** Hide/Show all LayerSwitcher controls depending on whether we are - * minimized or not - * - * @private - * - * @param {Boolean} minimize + /** + * Method: showToggle + * Hide/Show the toggle depending on whether the control is minimized + * + * Parameters: + * minimize - {Boolean} */ showToggle: function(minimize) { this.maximizeDiv.style.display = minimize ? '' : 'none'; @@ -400,6 +446,7 @@ OpenLayers.Control.OverviewMap.prototype = }, /** + * Method: update * Update the overview map after layers move. */ update: function() { @@ -416,6 +463,7 @@ OpenLayers.Control.OverviewMap.prototype = }, /** + * Method: isSuitableOverview * Determines if the overview map is suitable given the extent and * resolution of the main map. */ @@ -433,6 +481,10 @@ OpenLayers.Control.OverviewMap.prototype = (this.ovmap.getExtent().containsBounds(testExtent))); }, + /** + * Method updateOverview + * Called by if returns true + */ updateOverview: function() { var mapRes = this.map.getResolution(); var targetRes = this.ovmap.getResolution(); @@ -449,6 +501,10 @@ OpenLayers.Control.OverviewMap.prototype = this.updateRectToMap(); }, + /** + * Method: createMap + * Construct the map that this control contains + */ createMap: function() { // create the overview map var options = OpenLayers.Util.extend( @@ -470,6 +526,7 @@ OpenLayers.Control.OverviewMap.prototype = }, /** + * Method: updateRectToMap * Updates the extent rectangle position and size to match the map extent */ updateRectToMap: function() { @@ -487,6 +544,7 @@ OpenLayers.Control.OverviewMap.prototype = }, /** + * Method: updateMapToRect * Updates the map extent to match the extent rectangle position and size */ updateMapToRect: function() { @@ -496,9 +554,12 @@ OpenLayers.Control.OverviewMap.prototype = }, /** + * Method: getRectPxBounds * Get extent rectangle pixel bounds - * @returns An OpenLayers.Bounds wich is the extent rectangle's pixel - * bounds (relative to the parent element) + * + * Return: + * {} A bounds which is the extent rectangle's pixel + * bounds (relative to the parent element) */ getRectPxBounds: function() { var top = parseInt(this.extentRectangle.style.top); @@ -509,8 +570,11 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * Set extent rectangle pixel bounds. - * @param {OpenLayers.Bounds} pxBounds + * Method: setRectPxBounds + * Set extent rectangle pixel bounds. + * + * Parameters: + * pxBounds - {} */ setRectPxBounds: function(pxBounds) { var top = Math.max(pxBounds.top, 0); @@ -526,12 +590,16 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Bounds} lonLatBounds - * - * @returns An OpenLayers.Bounds which is the passed-in map lon/lat extent - * translated into pixel bounds for the overview map - * @type OpenLayers.Bounds - */ + * Method: getRectBoundsFromMapBounds + * Get the rect bounds from the map bounds. + * + * Parameters: + * lonLatBounds - {} + * + * Return: + * {}A bounds which is the passed-in map lon/lat extent + * translated into pixel bounds for the overview map + */ getRectBoundsFromMapBounds: function(lonLatBounds) { var leftBottomLonLat = new OpenLayers.LonLat(lonLatBounds.left, lonLatBounds.bottom); @@ -548,12 +616,16 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Bounds} pxBounds - * - * @returns An OpenLayers.Bounds which is the passed-in overview rect bounds - * translated into lon/lat bounds for the overview map - * @type OpenLayers.Bounds - */ + * Method: getMapBoundsFromRectBounds + * Get the map bounds from the rect bounds. + * + * Parameters: + * pxBounds - {} + * + * Return: + * {} Bounds which is the passed-in overview rect bounds + * translated into lon/lat bounds for the overview map + */ getMapBoundsFromRectBounds: function(pxBounds) { var leftBottomPx = new OpenLayers.Pixel(pxBounds.left, pxBounds.bottom); @@ -566,12 +638,16 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.Pixel} overviewMapPx - * - * @returns An OpenLayers.LonLat which is the passed-in overview map - * OpenLayers.Pixel, translated into lon/lat by the overview map - * @type OpenLayers.LonLat - */ + * Method: getLonLatFromOverviewPx + * Get a map location from a pixel location + * + * Parameters: + * overviewMapPx - {} + * + * Return: + * {} Location which is the passed-in overview map + * OpenLayers.Pixel, translated into lon/lat by the overview map + */ getLonLatFromOverviewPx: function(overviewMapPx) { var size = this.ovmap.size; var res = this.ovmap.getResolution(); @@ -585,12 +661,16 @@ OpenLayers.Control.OverviewMap.prototype = }, /** - * @param {OpenLayers.LonLat} lonlat - * - * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, - * translated into overview map pixels - * @type OpenLayers.Pixel - */ + * Method: getOverviewPxFromLonLat + * Get a pixel location from a map location + * + * Parameters: + * lonlat - {} + * + * Return: + * {} Location which is the passed-in OpenLayers.LonLat, + * translated into overview map pixels + */ getOverviewPxFromLonLat: function(lonlat) { var res = this.ovmap.getResolution(); var extent = this.ovmap.getExtent(); @@ -603,7 +683,10 @@ OpenLayers.Control.OverviewMap.prototype = return px; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of this class + */ CLASS_NAME: 'OpenLayers.Control.OverviewMap' }); diff --git a/lib/OpenLayers/Control/PanZoom.js b/lib/OpenLayers/Control/PanZoom.js index 2af98474e1..0a7b551ae1 100644 --- a/lib/OpenLayers/Control/PanZoom.js +++ b/lib/OpenLayers/Control/PanZoom.js @@ -4,9 +4,12 @@ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.PanZoom + * + * Inherits from: + * - */ OpenLayers.Control.PanZoom = OpenLayers.Class.create(); OpenLayers.Control.PanZoom.X = 4; @@ -14,17 +17,26 @@ OpenLayers.Control.PanZoom.Y = 4; OpenLayers.Control.PanZoom.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type int */ + /** + * APIProperty: slideFactor + * {Float} + */ slideFactor: 50, - /** @type Array of Button Divs */ + /** + * Property: buttons + * Array of Button Divs + */ buttons: null, - /** @type OpenLayers.Pixel */ + /** + * Property: position + * {} + */ position: null, /** - * @constructor + * Constructor: OpenLayers.PanZoom */ initialize: function() { this.position = new OpenLayers.Pixel(OpenLayers.Control.PanZoom.X, @@ -33,7 +45,7 @@ OpenLayers.Control.PanZoom.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { OpenLayers.Control.prototype.destroy.apply(this, arguments); @@ -47,10 +59,13 @@ OpenLayers.Control.PanZoom.prototype = }, /** - * @param {OpenLayers.Pixel} px + * Method: draw + * + * Parameters: + * px - {} * - * @returns A reference to the container div for the PanZoom control - * @type DOMElement + * Returns: + * {DOMElement} A reference to the container div for the PanZoom control */ draw: function(px) { // initialize our internal div @@ -79,15 +94,17 @@ OpenLayers.Control.PanZoom.prototype = }, /** - * @param {String} id - * @param {String} img - * @param {OpenLayers.Pixel} xy - * @param {OpenLayers.Size} sz + * Method: _addButton * - * @returns A Div (an alphaImageDiv, to be precise) that contains the - * image of the button, and has all the proper event handlers - * set. - * @type DOMElement + * Parameters: + * id - {String} + * img - {String} + * xy - {} + * sz - {} + * + * Returns: + * {DOMElement} A Div (an alphaImageDiv, to be precise) that contains the + * image of the button, and has all the proper event handlers set. */ _addButton:function(id, img, xy, sz) { var imgLocation = OpenLayers.Util.getImagesLocation() + img; @@ -116,9 +133,12 @@ OpenLayers.Control.PanZoom.prototype = }, /** - * @param {Event} evt - * - * @type Boolean + * Method: doubleClick + * + * Parameters: + * evt - {Event} + * + * Returns: {Boolean} */ doubleClick: function (evt) { OpenLayers.Event.stop(evt); @@ -126,7 +146,10 @@ OpenLayers.Control.PanZoom.prototype = }, /** - * @param {Event} evt + * Method: buttonDown + * + * Parameters: + * evt - {Event} */ buttonDown: function (evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; diff --git a/lib/OpenLayers/Control/PanZoomBar.js b/lib/OpenLayers/Control/PanZoomBar.js index 2a086241c3..6aaff259d8 100644 --- a/lib/OpenLayers/Control/PanZoomBar.js +++ b/lib/OpenLayers/Control/PanZoomBar.js @@ -4,38 +4,60 @@ /** - * @class - * * @requires OpenLayers/Control/PanZoom.js + * + * Class: OpenLayers.Control.PanZoomBar + * + * Inherits from: + * - + * - */ OpenLayers.Control.PanZoomBar = OpenLayers.Class.create(); OpenLayers.Control.PanZoomBar.prototype = OpenLayers.Class.inherit( OpenLayers.Control.PanZoom, { - /** @type int */ + /** + * APIProperty: zoomStopWidth + */ zoomStopWidth: 18, - /** @type int */ + /** + * APIProperty: zoomStopHeight + */ zoomStopHeight: 11, - /** @type DOMElement */ + /** + * Property: slider + */ slider: null, - /** @type OpenLayers.Events */ + /** + * Property: sliderEvents + * {} + */ sliderEvents: null, - /** @type DOMElement */ + /** + * Property: zoomBarDiv + * {DOMElement} + */ zoomBarDiv: null, - /** @type OpenLayers.Events */ + /** + * Property: divEvents + * {} + */ divEvents: null, + /** + * Constructor: + */ initialize: function() { OpenLayers.Control.PanZoom.prototype.initialize.apply(this, arguments); }, /** - * + * APIMethod: destroy */ destroy: function() { @@ -58,15 +80,19 @@ OpenLayers.Control.PanZoomBar.prototype = }, /** - * @param {OpenLayers.Map} map + * Method: setMap + * + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Control.PanZoom.prototype.setMap.apply(this, arguments); this.map.events.register("changebaselayer", this, this.redraw); }, - /** clear the div and start over. - * + /** + * Method: redraw + * clear the div and start over. */ redraw: function() { if (this.div != null) { @@ -76,7 +102,10 @@ OpenLayers.Control.PanZoomBar.prototype = }, /** - * @param {OpenLayers.Pixel} px + * Method: draw + * + * Parameters: + * px - {} */ draw: function(px) { // initialize our internal div @@ -101,7 +130,10 @@ OpenLayers.Control.PanZoomBar.prototype = }, /** - * @param {OpenLayers.Pixel} location where zoombar drawing is to start. + * Method: _addZoomBar + * + * Parameters: + * location - {} where zoombar drawing is to start. */ _addZoomBar:function(centered) { var imgLocation = OpenLayers.Util.getImagesLocation(); @@ -162,17 +194,22 @@ OpenLayers.Control.PanZoomBar.prototype = this.zoomStopHeight * this.map.getNumZoomLevels()); return centered; }, - /* + + /* + * Method: passEventToSlider * This function is used to pass events that happen on the div, or the map, * through to the slider, which then does its moving thing. - * @param {OpenLayers.Event} evt + * + * Parameters: + * evt - {} */ passEventToSlider:function(evt) { this.sliderEvents.handleBrowserEvent(evt); }, /* - * divClick: Picks up on clicks directly on the zoombar div + * Method: divClick + * Picks up on clicks directly on the zoombar div * and sets the zoom level appropriately. */ divClick: function (evt) { @@ -184,9 +221,12 @@ OpenLayers.Control.PanZoomBar.prototype = OpenLayers.Event.stop(evt); }, - /* + /* + * Method: zoomBarDown * event listener for clicks on the slider - * @param {OpenLayers.Event} evt + * + * Parameters: + * evt - {} */ zoomBarDown:function(evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -201,10 +241,14 @@ OpenLayers.Control.PanZoomBar.prototype = }, /* - * This is what happens when a click has occurred, and the client is dragging. - * Here we must ensure that the slider doesn't go beyond the bottom/top of the - * zoombar div, as well as moving the slider to its new visual location - * @param {OpenLayers.Event} evt + * Method: zoomBarDrag + * This is what happens when a click has occurred, and the client is + * dragging. Here we must ensure that the slider doesn't go beyond the + * bottom/top of the zoombar div, as well as moving the slider to its new + * visual location + * + * Parameters: + * evt - {} */ zoomBarDrag:function(evt) { if (this.mouseDragStart != null) { @@ -220,10 +264,13 @@ OpenLayers.Control.PanZoomBar.prototype = } }, - /* + /* + * Method: zoomBarUp * Perform cleanup when a mouseup event is received -- discover new zoom * level and switch to it. - * @param {OpenLayers.Event} evt + * + * Parameters: + * evt - {} */ zoomBarUp:function(evt) { if (!OpenLayers.Event.isLeftClick(evt)) return; @@ -239,7 +286,8 @@ OpenLayers.Control.PanZoomBar.prototype = } }, - /* + /* + * Method: moveZoomBar * Change the location of the slider to match the current zoom level. */ moveZoomBar:function() { diff --git a/lib/OpenLayers/Control/Panel.js b/lib/OpenLayers/Control/Panel.js index 520382b6fe..e54695a603 100644 --- a/lib/OpenLayers/Control/Panel.js +++ b/lib/OpenLayers/Control/Panel.js @@ -3,36 +3,44 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.Panel + * + * Inherits from: + * - */ OpenLayers.Control.Panel = OpenLayers.Class.create(); OpenLayers.Control.Panel.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { /** - * @type Array(OpenLayers.Control) + * Property: controls + * Array({}) */ controls: null, /** - * The control which is activated when the control is activated (turned - * on), which also happens at instantiation. - * @type OpenLayers.Control + * APIProperty: defaultControl + * The control which is activated when the control is + * activated (turned on), which also happens at instantiation. */ defaultControl: null, /** - * @constructor + * Constructor: OpenLayers.Control * - * @param {DOMElement} element - * @param {String} base + * Parameters: + * element - {DOMElement} + * base - {String} */ initialize: function(element) { OpenLayers.Control.prototype.initialize.apply(this, arguments); this.controls = []; }, + /** + * APIMethod: destroy + */ destroy: function() { OpenLayers.Control.prototype.destroy.apply(this, arguments); for(var i = this.controls.length - 1 ; i >= 0; i--) { @@ -41,6 +49,9 @@ OpenLayers.Control.Panel.prototype = } }, + /** + * APIMethod: activate + */ activate: function() { if (OpenLayers.Control.prototype.activate.apply(this, arguments)) { for(var i = 0; i < this.controls.length; i++) { @@ -55,6 +66,9 @@ OpenLayers.Control.Panel.prototype = } }, + /** + * APIMethod: deactivate + */ deactivate: function() { if (OpenLayers.Control.prototype.deactivate.apply(this, arguments)) { for(var i = 0; i < this.controls.length; i++) { @@ -68,7 +82,9 @@ OpenLayers.Control.Panel.prototype = }, /** - * @type DOMElement + * Method: draw + * + * Returns: {DOMElement} */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); @@ -81,7 +97,7 @@ OpenLayers.Control.Panel.prototype = }, /** - * @private + * Method: redraw */ redraw: function() { this.div.innerHTML = ""; @@ -98,6 +114,12 @@ OpenLayers.Control.Panel.prototype = } }, + /** + * APIMethod: activateControl + * + * Parameters: + * control - {} + */ activateControl: function (control) { if (!this.active) { return false; } if (control.type == OpenLayers.Control.TYPE_BUTTON) { @@ -125,10 +147,13 @@ OpenLayers.Control.Panel.prototype = }, /** + * APIMethod: addControls * To build a toolbar, you add a set of controls to it. addControls * lets you add a single control or a list of controls to the * Control Panel. - * @param {OpenLayers.Control} controls + * + * Parameters: + * controls - {} */ addControls: function(controls) { if (!(controls instanceof Array)) { @@ -159,7 +184,10 @@ OpenLayers.Control.Panel.prototype = this.redraw(); } }, - + + /** + * Method: onClick + */ onClick: function (ctrl, evt) { OpenLayers.Event.stop(evt ? evt : window.event); this.activateControl(ctrl); diff --git a/lib/OpenLayers/Control/Permalink.js b/lib/OpenLayers/Control/Permalink.js index 0235e719de..31463d3611 100644 --- a/lib/OpenLayers/Control/Permalink.js +++ b/lib/OpenLayers/Control/Permalink.js @@ -4,25 +4,35 @@ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.Permalink + * + * Inherits from: + * - */ OpenLayers.Control.Permalink = OpenLayers.Class.create(); OpenLayers.Control.Permalink.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type DOMElement */ + /** + * Property: element + * {DOMElement} + */ element: null, - /** @type String */ + /** + * APIProperty: base + * {String} + */ base: '', /** - * @constructor - * - * @param {DOMElement} element - * @param {String} base + * Constructor: OpenLayers.Control.Permalink + * + * Parameters: + * element - {DOMElement} + * base - {String} */ initialize: function(element, base) { OpenLayers.Control.prototype.initialize.apply(this, arguments); @@ -33,7 +43,7 @@ OpenLayers.Control.Permalink.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { if (this.element.parentNode == this.div) { @@ -46,9 +56,12 @@ OpenLayers.Control.Permalink.prototype = OpenLayers.Control.prototype.destroy.apply(this, arguments); }, - /** Set the map property for the control. + /** + * Method: setMap + * Set the map property for the control. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Control.prototype.setMap.apply(this, arguments); @@ -67,7 +80,9 @@ OpenLayers.Control.Permalink.prototype = }, /** - * @type DOMElement + * Method: draw + * + * Returns: {DOMElement} */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); @@ -85,7 +100,7 @@ OpenLayers.Control.Permalink.prototype = }, /** - * + * Method: updateLink */ updateLink: function() { var center = this.map.getCenter(); diff --git a/lib/OpenLayers/Control/Scale.js b/lib/OpenLayers/Control/Scale.js index 3c7cf41456..ad381d7755 100644 --- a/lib/OpenLayers/Control/Scale.js +++ b/lib/OpenLayers/Control/Scale.js @@ -4,21 +4,29 @@ /** - * @class - * * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.Scale + * Display a small scale indicator on the map. + * Inherits from: + * - */ OpenLayers.Control.Scale = OpenLayers.Class.create(); OpenLayers.Control.Scale.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type DOMElement */ + + /** + * Parameter: element + * {DOMElement} + */ element: null, /** - * @constructor + * Constructor: OpenLayers.Control.Scale * - * @param {DOMElement} element - * @param {String} base + * Parameters: + * element - {DOMElement} + * base - {String} */ initialize: function(element) { OpenLayers.Control.prototype.initialize.apply(this, arguments); @@ -26,7 +34,9 @@ OpenLayers.Control.Scale.prototype = }, /** - * @type DOMElement + * Method: draw + * + * Returns: {DOMElemen}t */ draw: function() { OpenLayers.Control.prototype.draw.apply(this, arguments); @@ -42,7 +52,7 @@ OpenLayers.Control.Scale.prototype = }, /** - * + * Method: updateScale */ updateScale: function() { var scale = this.map.getScale(); diff --git a/lib/OpenLayers/Control/SelectFeature.js b/lib/OpenLayers/Control/SelectFeature.js index 4aa31cd717..d1a6215c60 100644 --- a/lib/OpenLayers/Control/SelectFeature.js +++ b/lib/OpenLayers/Control/SelectFeature.js @@ -4,64 +4,77 @@ /** - * Draws features on a vector layer when active. - * - * @class * @requires OpenLayers/Control.js * @requires OpenLayers/Feature/Vector.js + * + * Class: OpenLayers.Control.SelectFeature + * Draws features on a vector layer when active. + * + * Inherits from: + * - */ OpenLayers.Control.SelectFeature = OpenLayers.Class.create(); OpenLayers.Control.SelectFeature.prototype = OpenLayers.Class.inherit(OpenLayers.Control, { /** - * @type {Boolean} Allow selection of multiple geometries + * APIProperty: multiple + * {Boolean} Allow selection of multiple geometries */ multiple: false, /** - * @type {Boolean} Select on mouse over and deselect on mouse out. If - * true, this ignores clicks and only listens to mouse moves. + * APIProperty: hover + * {Boolean} Select on mouse over and deselect on mouse out. If true, this + * ignores clicks and only listens to mouse moves. */ hover: false, /** - * @type {Function} Optional function to be called when a feature is selected. - * The function should expect to be called with a feature. + * APIProperty: onSelect + * {Function} Optional function to be called when a feature is selected. + * The function should expect to be called with a feature. */ onSelect: function() {}, /** - * @type {Function} Optional function to be called when a feature is unselected. + * APIProperty: onUnselect + * {Function} Optional function to be called when a feature is unselected. * The function should expect to be called with a feature. */ onUnselect: function() {}, /** - * @type {OpenLayers.Layer.Vector} + * Property: layer + * {} */ layer: null, /** - * @type {Object} The functions that are sent to the handler for callback + * APIProperty: callbacks + * {Object} The functions that are sent to the handler for callback */ callbacks: null, /** - * @type {Object} Hash of styles + * APIProperty: selectStyle + * {Object} Hash of styles */ selectStyle: OpenLayers.Feature.Vector.style['select'], /** - * @type {OpenLayers.Handler.Feature} - * @private + * Property: handler + * {} */ handler: null, /** - * @param {OpenLayers.Layer.Vector} layer - * @param {OpenLayers.Handler} handler - * @param {Object} options + * Constructor: + * + * Parameters: + * layer - {} + * handler - {} + * options - {Object} */ initialize: function(layer, options) { OpenLayers.Control.prototype.initialize.apply(this, [options]); @@ -75,8 +88,11 @@ OpenLayers.Control.SelectFeature.prototype = }, /** + * Method: downFeature * Called when the feature handler detects a mouse-down on a feature - * @param {OpenLayers.Vector.Feature} + * + * Parameters: + * feature - {} */ downFeature: function(feature) { if(this.hover) { @@ -103,9 +119,12 @@ OpenLayers.Control.SelectFeature.prototype = }, /** + * Method: overFeature * Called when the feature handler detects a mouse-over on a feature. * Only responds if this.hover is true. - * @param {OpenLayers.Feature.Vector} + * + * Parameters: + * feature - {} */ overFeature: function(feature) { if(!this.hover) { @@ -117,9 +136,12 @@ OpenLayers.Control.SelectFeature.prototype = }, /** + * Method: outFeature * Called when the feature handler detects a mouse-out on a feature. * Only responds if this.hover is true. - * @param {OpenLayers.Feature.Vector} + * + * Parameters: + * feature - {} */ outFeature: function(feature) { if(!this.hover) { @@ -129,9 +151,12 @@ OpenLayers.Control.SelectFeature.prototype = }, /** + * Method: select * Add feature to the layer's selectedFeature array, render the feature as * selected, and call the onSelect function. - * @param {OpenLayers.Feature.Vector} feature + * + * Parameters: + * feature - {} */ select: function(feature) { // Store feature style for restoration later @@ -144,9 +169,12 @@ OpenLayers.Control.SelectFeature.prototype = }, /** + * Method: unselect * Remove feature from the layer's selectedFeature array, render the feature as * normal, and call the onUnselect function. - * @param {OpenLayers.Feature.Vector} feature + * + * Parameters: + * feature - {} */ unselect: function(feature) { // Store feature style for restoration later @@ -158,9 +186,12 @@ OpenLayers.Control.SelectFeature.prototype = this.onUnselect(feature); }, - /** Set the map property for the control. + /** + * Method: setMap + * Set the map property for the control. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { this.handler.setMap(map); diff --git a/lib/OpenLayers/Control/ZoomBox.js b/lib/OpenLayers/Control/ZoomBox.js index 8f111943cf..fe18447582 100644 --- a/lib/OpenLayers/Control/ZoomBox.js +++ b/lib/OpenLayers/Control/ZoomBox.js @@ -3,25 +3,37 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Control.js * @requires OpenLayers/Handler/Box.js + * + * Class: OpenLayers.Control.ZoomBox + * + * Inherits from: + * - */ OpenLayers.Control.ZoomBox = OpenLayers.Class.create(); OpenLayers.Control.ZoomBox.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type OpenLayers.Control.TYPE_* */ + /** + * Property: type + * {OpenLayers.Control.TYPE} + */ type: OpenLayers.Control.TYPE_TOOL, /** - * + * Method: draw */ draw: function() { this.handler = new OpenLayers.Handler.Box( this, {done: this.zoomBox}, {keyMask: this.keyMask} ); }, + /** + * Method: zoomBox + * + * Parameters: + * position - {} or {} + */ zoomBox: function (position) { if (position instanceof OpenLayers.Bounds) { var minXY = this.map.getLonLatFromPixel( diff --git a/lib/OpenLayers/Control/ZoomToMaxExtent.js b/lib/OpenLayers/Control/ZoomToMaxExtent.js index 16cff056b2..1bac1adf6f 100644 --- a/lib/OpenLayers/Control/ZoomToMaxExtent.js +++ b/lib/OpenLayers/Control/ZoomToMaxExtent.js @@ -3,17 +3,28 @@ * for the full text of the license. */ /** - * @class - * - * Imlements a very simple button control. * @requires OpenLayers/Control.js + * + * Class: OpenLayers.Control.ZoomToMaxExtent + * Imlements a very simple button control. Designed to be used with a + * . + * + * Inherits from: + * - */ OpenLayers.Control.ZoomToMaxExtent = OpenLayers.Class.create(); OpenLayers.Control.ZoomToMaxExtent.prototype = OpenLayers.Class.inherit( OpenLayers.Control, { - /** @type OpenLayers.Control.TYPE_* */ + /** + * Property: type + * TYPE_BUTTON. + */ type: OpenLayers.Control.TYPE_BUTTON, + /* + * Method: trigger + * Do the zoom. + */ trigger: function() { if (this.map) { this.map.zoomToMaxExtent(); diff --git a/lib/OpenLayers/Events.js b/lib/OpenLayers/Events.js index 014a334c35..c104676661 100644 --- a/lib/OpenLayers/Events.js +++ b/lib/OpenLayers/Events.js @@ -2,74 +2,115 @@ * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ + /** * @requires OpenLayers/Util.js - * - * @class (Not really a class, but kind of) - * + * + * Title: OpenLayers.Events + * + * Class: OpenLayers.Event + * Utility functions for event handling. */ OpenLayers.Event = { - /** A hashtable cache of the event observers. - * Keyed by element._eventCacheID - * - * @type Object - */ - observers: false, + /** + * Property: observers + * {Object} A hashtable cache of the event observers. Keyed by + * element._eventCacheID + */ + observers: false, - /** @final @type int */ - KEY_BACKSPACE: 8, + /** + * Constant: KEY_BACKSPACE + * {int} + */ + KEY_BACKSPACE: 8, - /** @final @type int */ - KEY_TAB: 9, + /** + * Constant: KEY_TAB + * {int} + */ + KEY_TAB: 9, - /** @final @type int */ - KEY_RETURN: 13, + /** + * Constant: KEY_RETURN + * {int} + */ + KEY_RETURN: 13, - /** @final @type int */ - KEY_ESC: 27, + /** + * Constant: KEY_ESC + * {int} + */ + KEY_ESC: 27, - /** @final @type int */ - KEY_LEFT: 37, + /** + * Constant: KEY_LEFT + * {int} + */ + KEY_LEFT: 37, - /** @final @type int */ - KEY_UP: 38, + /** + * Constant: KEY_UP + * {int} + */ + KEY_UP: 38, - /** @final @type int */ - KEY_RIGHT: 39, + /** + * Constant: KEY_RIGHT + * {int} + */ + KEY_RIGHT: 39, - /** @final @type int */ - KEY_DOWN: 40, + /** + * Constant: KEY_DOWN + * {int} + */ + KEY_DOWN: 40, - /** @final @type int */ - KEY_DELETE: 46, + /** + * Constant: KEY_DELETE + * {int} + */ + KEY_DELETE: 46, /** - * @param {Event} event + * Method: element + * Cross browser event element detection. * - * @returns The element that caused the alert - * @type DOMElement + * Parameters: + * event - {Event} + * + * Returns: + * {DOMElement} The element that caused the event */ element: function(event) { return event.target || event.srcElement; }, /** - * @param {Event} event + * Method: isLeftClick + * Determine whether event was caused by a left click. + * + * Parameters: + * event - {Event} * - * @returns Whether or not the event was the result of a left click - * @type boolean + * Returns: + * {Boolean} */ isLeftClick: function(event) { return (((event.which) && (event.which == 1)) || ((event.button) && (event.button == 1))); }, - /** Stops an event from propagating. - * - * @param {Event} event - * @param {Boolean} allowDefault If true, we stop the event chain but + /** + * Method: stop + * Stops an event from propagating. + * + * Parameters: + * event - {Event} + * allowDefault - {Boolean} If true, we stop the event chain but * still allow the default browser * behaviour (text selection, radio-button * clicking, etc) @@ -93,12 +134,15 @@ OpenLayers.Event = { }, /** - * @param {Event} event - * @param {String} tagName + * Method: findElement * - * @returns The first node with the given tagName, starting from the node - * the event was triggered on and traversing the DOM upwards - * @type DOMElement + * Parameters: + * event - {Event} + * tagName - {String} + * + * Return: + * {DOMElement} The first node with the given tagName, starting from the + * node the event was triggered on and traversing the DOM upwards */ findElement: function(event, tagName) { var element = OpenLayers.Event.element(event); @@ -109,11 +153,13 @@ OpenLayers.Event = { }, /** - * @param {DOMElement || String} elementParam - * @param {String} name - * @param {function} observer - * @param {Boolean} useCapture + * Method: observe * + * Parameters: + * elementParam - {DOMElement || String} + * name - {String} + * observer - {function} + * useCapture - {Boolean} */ observe: function(elementParam, name, observer, useCapture) { var element = OpenLayers.Util.getElement(elementParam); @@ -162,11 +208,14 @@ OpenLayers.Event = { } }, - /** Given the id of an element to stop observing, cycle through the + /** + * Method: stopObservingElement + * Given the id of an element to stop observing, cycle through the * element's cached observers, calling stopObserving on each one, * skipping those entries which can no longer be removed. * - * @param {DOMElement || String} elementParam + * parameters: + * elementParam - {DOMElement || String} */ stopObservingElement: function(elementParam) { var element = OpenLayers.Util.getElement(elementParam); @@ -176,9 +225,11 @@ OpenLayers.Event = { }, /** - * @private - * - * @param {Array(Object)} elementObservers Array of (element, name, + * Method: _removeElementObservers + * *Private*. + * + * Parameters: + * elementObservers - {Array(Object)} Array of (element, name, * observer, usecapture) objects, * taken directly from hashtable */ @@ -196,13 +247,16 @@ OpenLayers.Event = { }, /** - * @param {DOMElement || String} elementParam - * @param {String} name - * @param {function} observer - * @param {Boolean} useCapture + * Method: stopObserving * - * @returns Whether or not the event observer was removed - * @type Boolean + * Parameters: + * elementParam - {DOMElement || String} + * name - {String} + * observer - {function} + * useCapture - {Boolean} + * + * Return: + * {Boolean} Whether or not the event observer was removed */ stopObserving: function(elementParam, name, observer, useCapture) { useCapture = useCapture || false; @@ -251,7 +305,9 @@ OpenLayers.Event = { return foundEntry; }, - /** Cycle through all the element entries in the events cache and call + /** + * Method: unloadCache + * Cycle through all the element entries in the events cache and call * stopObservingElement on each. */ unloadCache: function() { @@ -279,12 +335,15 @@ if (window.Event) { } /** - * @class + * Class: OpenLayers.Events */ OpenLayers.Events = OpenLayers.Class.create(); OpenLayers.Events.prototype = { - /** @final @type Array: supported events */ + /** + * Constant: BROWSER_EVENTS + * {Array} supported events + */ BROWSER_EVENTS: [ "mouseover", "mouseout", "mousedown", "mouseup", "mousemove", @@ -292,37 +351,52 @@ OpenLayers.Events.prototype = { "resize", "focus", "blur" ], - /** Hashtable of Array(Function): events listener functions - * @type Object */ - listeners: null, + /** + * Property: listeners + * {Object} Hashtable of Array(Function): events listener functions + */ + listeners: null, - /** @type Object: the code object issuing application events */ - object: null, + /** + * Property: object + * {Object} the code object issuing application events + */ + object: null, - /** @type DOMElement: the DOM element receiving browser events */ - element: null, + /** + * Property: element + * {DOMElement} the DOM element receiving browser events + */ + element: null, - /** @type Array: list of support application events */ - eventTypes: null, + /** + * Property: eventTypes + * {Array} list of support application events + */ + eventTypes: null, + + /** + * Property: eventHandler + * {Function} bound event handler attached to elements + */ + eventHandler: null, + + /** + * Property: fallThrough + * {Boolean} + */ + fallThrough: null, /** - * @type Function: bound event handler attached to elements - * @private - */ - eventHandler: null, - - /** @type Boolean */ - fallThrough: null, - - /** - * @constructor - * - * @param {OpenLayers.Map} object The js object to which this Events object - * is being added - * @param {DOMElement} element A dom element to respond to browser events - * @param {Array} eventTypes Array of custom application events - * @param {Boolean} fallThrough Allow events to fall through after these - * have been handled? + * Constructor: OpenLayers.Events + * Construct an OpenLayers.Events object. + * + * Parameters: + * object - {Object} The js object to which this Events object is being + * added element - {DOMElement} A dom element to respond to browser events + * eventTypes - {Array} Array of custom application events + * fallThrough - {Boolean} Allow events to fall through after these have + * been handled? */ initialize: function (object, element, eventTypes, fallThrough) { this.object = object; @@ -351,7 +425,7 @@ OpenLayers.Events.prototype = { }, /** - * + * Method: destroy */ destroy: function () { if (this.element) { @@ -367,7 +441,10 @@ OpenLayers.Events.prototype = { }, /** - * @param {HTMLDOMElement} element a DOM element to attach browser events to + * Method: attachToElement + * + * Parameters: + * element - {HTMLDOMElement} a DOM element to attach browser events to */ attachToElement: function (element) { for (var i = 0; i < this.BROWSER_EVENTS.length; i++) { @@ -387,26 +464,30 @@ OpenLayers.Events.prototype = { }, /** - * @param {String} type Name of the event to register - * @param {Object} obj The object to bind the context to for the callback#. - * If no object is specified, default is the Events's - * 'object' property. - * @param {Function} func The callback function. If no callback is - * specified, this function does nothing. - * - * #When the event is triggered, the 'func' function will be called, in the - * context of 'obj'. Imagine we were to register an event, specifying an - * OpenLayers.Bounds Object as 'obj'. When the event is triggered, the - * context in the callback function will be our Bounds object. This means - * that within our callback function, we can access the properties and - * methods of the Bounds object through the "this" variable. So our - * callback could execute something like: - * - * leftStr = "Left: " + this.left; + * Method: register + * Register an event on the events object. + * + * When the event is triggered, the 'func' function will be called, in the + * context of 'obj'. Imagine we were to register an event, specifying an + * OpenLayers.Bounds Object as 'obj'. When the event is triggered, the + * context in the callback function will be our Bounds object. This means + * that within our callback function, we can access the properties and + * methods of the Bounds object through the "this" variable. So our + * callback could execute something like: + * : leftStr = "Left: " + this.left; * * or * - * centerStr = "Center: " + this.getCenterLonLat(); + * : centerStr = "Center: " + this.getCenterLonLat(); + * + * Parameters: + * type - {String} Name of the event to register + * obj - {Object} The object to bind the context to for the callback#. + * If no object is specified, default is the Events's + * 'object' property. + * func - {Function} The callback function. If no callback is + * specified, this function does nothing. + * * */ register: function (type, obj, func) { @@ -425,12 +506,15 @@ OpenLayers.Events.prototype = { /** * TODO: get rid of this in 3.0 - Decide whether listeners should be * called in the order they were registered or in reverse order. - * - * @param {String} type Name of the event to register - * @param {Object} obj The object to bind the context to for the callback#. + * + * Method: registerPriority + * + * Parameters: + * type - {String} Name of the event to register + * obj - {Object} The object to bind the context to for the callback#. * If no object is specified, default is the Events's * 'object' property. - * @param {Function} func The callback function. If no callback is + * func - {Function} The callback function. If no callback is * specified, this function does nothing. */ registerPriority: function (type, obj, func) { @@ -447,9 +531,12 @@ OpenLayers.Events.prototype = { }, /** - * @param {String} type - * @param {Object} obj If none specified, defaults to this.object - * @param {Function} func + * Method: unregister + * + * Parameters: + * type - {String} + * obj - {Object} If none specified, defaults to this.object + * func - {Function} */ unregister: function (type, obj, func) { if (obj == null) { @@ -466,10 +553,13 @@ OpenLayers.Events.prototype = { } }, - /** Remove all listeners for a given event type. If type is not registered, + /** + * Method: remove + * Remove all listeners for a given event type. If type is not registered, * does nothing. - * - * @param {String} type + * + * Parameters: + * type - {String} */ remove: function(type) { if (this.listeners[type] != null) { @@ -477,10 +567,13 @@ OpenLayers.Events.prototype = { } }, - /** Trigger a specified registered event + /** + * Method: triggerEvent + * Trigger a specified registered event * - * @param {String} type - * @param {Event} evt + * Parameters: + * type - {String} + * evt - {Event} */ triggerEvent: function (type, evt) { @@ -519,13 +612,16 @@ OpenLayers.Events.prototype = { } }, - /** Basically just a wrapper to the triggerEvent() function, but takes + /** + * Method: handleBrowserEvent + * Basically just a wrapper to the triggerEvent() function, but takes * care to set a property 'xy' on the event with the current mouse * position. - * - * @private - * - * @param {Event} evt + * + * Private function. + * + * Parameters: + * evt - {Event} */ handleBrowserEvent: function (evt) { evt.xy = this.getMousePosition(evt); @@ -533,12 +629,15 @@ OpenLayers.Events.prototype = { }, /** - * @private + * Method: getMousePosition + * *Private* * - * @param {Event} evt + * Parameters: + * evt - {Event} * - * @returns The current xy coordinate of the mouse, adjusted for offsets - * @type OpenLayers.Pixel + * Returns + * {} The current xy coordinate of the mouse, adjusted + * for offsets */ getMousePosition: function (evt) { if (!this.element.offsets) { diff --git a/lib/OpenLayers/Feature.js b/lib/OpenLayers/Feature.js index 069a904ba3..4131fcdf98 100644 --- a/lib/OpenLayers/Feature.js +++ b/lib/OpenLayers/Feature.js @@ -4,41 +4,69 @@ /** - * @class - * * @requires OpenLayers/Util.js * @requires OpenLayers/Marker.js + * + * Class: OpenLayers.Feature + * Features are combinations of geography and attributes. The OpenLayers.Feature + * class specifically combines a marker and a lonlat. */ OpenLayers.Feature = OpenLayers.Class.create(); OpenLayers.Feature.prototype= { - /** @type OpenLayers.Events */ - events:null, - - /** @type OpenLayers.Layer */ - layer: null, - - /** @type String */ - id: null, - - /** @type OpenLayers.LonLat */ - lonlat:null, - - /** @type Object */ - data:null, - - /** @type OpenLayers.Marker */ - marker: null, - - /** @type OpenLayers.Popup */ - popup: null, + /** + * Property: events + * {} + */ + events: null, /** - * @constructor + * Property: layer + * {} + */ + layer: null, + + /** + * Property: id + * {String} + */ + id: null, + + /** + * Property: lonlat + * {} + */ + lonlat: null, + + /** + * Property: data + * {Object} + */ + data: null, + + /** + * Property: marker + * {} + */ + marker: null, + + /** + * Property: popup + * {} + */ + popup: null, + + /** + * Constructor: OpenLayers.Feature + * Constructor for features. + * + * Parameters: + * layer - {} + * lonlat - {} + * data - {Object} * - * @param {OpenLayers.Layer} layer - * @param {OpenLayers.LonLat} lonlat - * @param {Object} data + * Return: + * {} */ initialize: function(layer, lonlat, data) { this.layer = layer; @@ -47,8 +75,9 @@ OpenLayers.Feature.prototype= { this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_"); }, - /** - * + /** + * Method: destroy + * nullify references to prevent circular references and memory leaks */ destroy: function() { @@ -79,9 +108,11 @@ OpenLayers.Feature.prototype= { }, /** - * @returns Whether or not the feature is currently visible on screen + * Method: onScreen + * + * Returns: + * {Boolean} Whether or not the feature is currently visible on screen * (based on its 'lonlat' property) - * @type Boolean */ onScreen:function() { @@ -95,13 +126,16 @@ OpenLayers.Feature.prototype= { /** - * @returns A Marker Object created from the 'lonlat' and 'icon' properties + * Method: createMarker + * Based on the data associated with the Feature, create and return a marker object. + * + * Return: + * {} A Marker Object created from the 'lonlat' and 'icon' properties * set in this.data. If no 'lonlat' is set, returns null. If no * 'icon' is set, OpenLayers.Marker() will load the default image. * - * Note: this.marker is set to return value + * Note - this.marker is set to return value * - * @type OpenLayers.Marker */ createMarker: function() { @@ -113,7 +147,10 @@ OpenLayers.Feature.prototype= { return this.marker; }, - /** If user overrides the createMarker() function, s/he should be able + /** + * Method: destroyMarker + * Destroys marker. + * If user overrides the createMarker() function, s/he should be able * to also specify an alternative function for destroying it */ destroyMarker: function() { @@ -121,17 +158,22 @@ OpenLayers.Feature.prototype= { }, /** - * @param {Boolean} closeBox create popup with closebox or not - * @returns A Popup Object created from the 'lonlat', 'popupSize', - * and 'popupContentHTML' properties set in this.data. It uses - * this.marker.icon as default anchor. - * - * If no 'lonlat' is set, returns null. - * If no this.marker has been created, no anchor is sent. + * Method: createPopup + * Creates a popup object created from the 'lonlat', 'popupSize', + * and 'popupContentHTML' properties set in this.data. It uses + * this.marker.icon as default anchor. + * + * If no 'lonlat' is set, returns null. + * If no this.marker has been created, no anchor is sent. * - * Note: this.popup is set to return value + * Note - this.popup is set to return value + * + * Parameters: + * closeBox - {Boolean} create popup with closebox or not + * + * Returns: + * {} * - * @type OpenLayers.Popup.AnchoredBubble */ createPopup: function(closeBox) { @@ -150,7 +192,11 @@ OpenLayers.Feature.prototype= { }, - /** As with the marker, if user overrides the createPopup() function, s/he + /** + * Method: destroyPopup + * Destroys the popup created via createPopup. + * + * As with the marker, if user overrides the createPopup() function, s/he * should also be able to override the destruction */ destroyPopup: function() { diff --git a/lib/OpenLayers/Feature/Vector.js b/lib/OpenLayers/Feature/Vector.js index 0a6cc240e2..41b2e3aa95 100644 --- a/lib/OpenLayers/Feature/Vector.js +++ b/lib/OpenLayers/Feature/Vector.js @@ -12,36 +12,60 @@ OpenLayers.State = { } /** - * @class - * * @requires OpenLayers/Feature.js * @requires OpenLayers/Util.js + * + * Class: OpenLayers.Feature.Vector + * Vector features use the OpenLayers.Geometry classes as geometry description. + * They have an 'attributes' property, which is the data object, and a 'style' + * property, the default values of which are defined in the + * objects. + * + * Inherits from: + * - */ OpenLayers.Feature.Vector = OpenLayers.Class.create(); OpenLayers.Feature.Vector.prototype = OpenLayers.Class.inherit( OpenLayers.Feature, { - /** @type String */ - fid: null, - - /** @type OpenLayers.Geometry */ - geometry:null, - - /** @type Object */ - attributes: null, - - /** @type String */ - state: null, - - /** @type Object */ - style: null, + /** + * Property: fid + * {String} + */ + fid: null, /** + * Property: geometry + * {} + */ + geometry: null, + + /** + * Property: attributes + * {Object} + */ + attributes: null, + + /** + * Property: state + * {String} + */ + state: null, + + /** + * Property: style + * {Object} + */ + style: null, + + /** + * Constructor: OpenLayers.Feature.Vector * Create a vector feature. - * @constructor * - * @param {OpenLayers.Geometry} geometry - * @param {Object} data + * Parameters: + * geometry - {} + * data - {Object} + * style - {Object} */ initialize: function(geometry, data, style) { OpenLayers.Feature.prototype.initialize.apply(this, [null, null, data]); @@ -55,8 +79,9 @@ OpenLayers.Feature.Vector.prototype = this.style = style ? style : null; }, - /** - * + /** + * Method: destroy + * nullify references to prevent circular references and memory leaks */ destroy: function() { if (this.layer) { @@ -69,8 +94,10 @@ OpenLayers.Feature.Vector.prototype = }, /** - * @returns An exact clone of this OpenLayers.Feature - * @type OpenLayers.Feature + * Method: clone + * + * Returns: + * An exact clone of this OpenLayers.Feature */ clone: function (obj) { if (obj == null) { @@ -84,30 +111,32 @@ OpenLayers.Feature.Vector.prototype = }, /** + * Method: onScreen * HACK - we need to rewrite this for non-point geometry - * @returns null - we need to rewrite this for non-point geometry - * @type Boolean + * + * Return: + * {Boolean} For now just returns null */ onScreen:function() { return null; }, /** - * + * Method: createMarker * HACK - we need to decide if all vector features should be able to - * create markers + * create markers * - * @returns null - * - * @type OpenLayers.Marker + * Return: + * {} For now just returns null */ createMarker: function() { return null; }, /** + * Method: destroyMarker * HACK - we need to decide if all vector features should be able to - * delete markers + * delete markers * * If user overrides the createMarker() function, s/he should be able * to also specify an alternative function for destroying it @@ -117,22 +146,28 @@ OpenLayers.Feature.Vector.prototype = }, /** + * Method: createPopup * HACK - we need to decide if all vector features should be able to - * create popups + * create popups * - * @returns null + * Return: + * {} For now just returns null */ createPopup: function() { return null; }, /** - * @param {OpenLayers.LonLat} lonlat - * @param {float} toleranceLon Optional tolerance in Geometric Coords - * @param {float} toleranceLat Optional tolerance in Geographic Coords + * Method: atPoint + * Determins whether the feature intersects with the specified location. * - * @returns Whether or not the feature is at the specified location - * @type Boolean + * Parameters: + * lonlat - {} + * toleranceLon - {float} Optional tolerance in Geometric Coords + * toleranceLat - {float} Optional tolerance in Geographic Coords + * + * Returns: + * {Boolean} Whether or not the feature is at the specified location */ atPoint: function(lonlat, toleranceLon, toleranceLat) { var atPoint = false; @@ -144,7 +179,7 @@ OpenLayers.Feature.Vector.prototype = }, /** - * + * Method: destroyPopup * HACK - we need to decide if all vector features should be able to * delete popups */ @@ -153,8 +188,11 @@ OpenLayers.Feature.Vector.prototype = }, /** + * Method: toState * Sets the new state - * @param {String} state + * + * Parameters: + * state - {String} */ toState: function(state) { if (state == OpenLayers.State.UPDATE) { @@ -196,7 +234,31 @@ OpenLayers.Feature.Vector.prototype = }); -// styles for feature rendering +/* + * Constant: OpenLayers.Feature.Vector.style + * OpenLayers features can have a number of + * style attributes. The 'default' style will + * typically be used if no other style is specified. + * + * Default style properties: + * + * - fillColor: "#ee9900", + * - fillOpacity: 0.4, + * - hoverFillColor: "white", + * - hoverFillOpacity: 0.8, + * - strokeColor: "#ee9900", + * - strokeOpacity: 1, + * - strokeWidth: 1, + * - strokeLinecap: "round", + * - hoverStrokeColor: "red", + * - hoverStrokeOpacity: 1, + * - hoverStrokeWidth: 0.2, + * - pointRadius: 6, + * - hoverPointRadius: 1, + * - hoverPointUnit: "%", + * - pointerEvents: "visiblePainted" + */ + OpenLayers.Feature.Vector.style = { 'default': { fillColor: "#ee9900", diff --git a/lib/OpenLayers/Feature/WFS.js b/lib/OpenLayers/Feature/WFS.js index da424f727d..87709c7424 100644 --- a/lib/OpenLayers/Feature/WFS.js +++ b/lib/OpenLayers/Feature/WFS.js @@ -4,19 +4,27 @@ /** - * @class - * * @requires OpenLayers/Feature.js + * + * Class: OpenLayers.Feature.WFS + * WFS handling class, for use as a featureClass on the WFS layer for handling + * 'point' WFS types. Good for subclassing when creating a custom WFS like + * XML application. + * + * Inherits from: + * - */ OpenLayers.Feature.WFS = OpenLayers.Class.create(); OpenLayers.Feature.WFS.prototype = OpenLayers.Class.inherit( OpenLayers.Feature, { /** - * @constructor - * - * @param {OpenLayers.Layer} layer - * @param {XMLNode} xmlNode + * Constructor: OpenLayers.Feature.WFS + * Create a WFS feature. + * + * Parameters: + * layer - {} + * xmlNode - {XMLNode} */ initialize: function(layer, xmlNode) { var newArguments = arguments; @@ -27,6 +35,10 @@ OpenLayers.Feature.WFS.prototype = this.layer.addMarker(this.marker); }, + /** + * Method: destroy + * nullify references to prevent circular references and memory leaks + */ destroy: function() { if (this.marker != null) { this.layer.removeMarker(this.marker); @@ -35,10 +47,17 @@ OpenLayers.Feature.WFS.prototype = }, /** - * @param {XMLNode} xmlNode + * Method: processXMLNode + * When passed an xmlNode, parses it for a GML point, and passes + * back an object describing that point. + * + * For subclasses of Feature.WFS, this is the feature to change. + * + * Parameters: + * xmlNode - {XMLNode} * - * @returns Data Object with 'id', 'lonlat', and private properties set - * @type Object + * Return: + * {Object} Data Object with 'id', 'lonlat', and private properties set */ processXMLNode: function(xmlNode) { //this should be overridden by subclasses diff --git a/lib/OpenLayers/Format.js b/lib/OpenLayers/Format.js index bca2681f1b..a24f8c9fb9 100644 --- a/lib/OpenLayers/Format.js +++ b/lib/OpenLayers/Format.js @@ -3,35 +3,63 @@ * for the full text of the license. */ /** - * Base class for format reading/writing. * @requires OpenLayers/Util.js + * + * Class: OpenLayers.Format + * Base class for format reading/writing a variety of formats. Subclasses + * of OpenLayers.Format are expected to have read and write methods. */ OpenLayers.Format = OpenLayers.Class.create(); OpenLayers.Format.prototype = { + /** + * Constructor: OpenLayers.Format + * Instances of this class are not useful. See one of the subclasses. + * + * Parameters: + * options - {Object} An optional object with properties to set on the + * format + * + * Return: + * An instance of OpenLayers.Format + */ initialize: function(options) { OpenLayers.Util.extend(this, options); }, /** - * Read data from a string, and return a list of features. + * Method: read + * Read data from a string, and return an object whose type depends on the + * subclass. * - * @param {string} data data to read/parse. + * Parameters: + * data - {string} Data to read/parse. + * + * Return: + * Depends on the subclass */ - read: function(data) { - alert("Read not implemented."); - }, + read: function(data) { + alert("Read not implemented."); + }, /** - * Accept Feature Collection, and return a string. - * - * @param {Array} List of features to serialize into a string. + * Method: write + * Accept an object, and return a string. + * + * Parameters: + * object - {Object} Object to be serialized + * + * Return: + * {String} A string representation of the object. */ - write: function(features) { - alert("Write not implemented."); - }, + write: function(object) { + alert("Write not implemented."); + }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} OpenLayers.Format + */ CLASS_NAME: "OpenLayers.Format" }; diff --git a/lib/OpenLayers/Format/GML.js b/lib/OpenLayers/Format/GML.js index 59bd3b335a..965efc4384 100644 --- a/lib/OpenLayers/Format/GML.js +++ b/lib/OpenLayers/Format/GML.js @@ -3,41 +3,74 @@ * for the full text of the license. */ /** - * Read/WRite GML. * @requires OpenLayers/Format.js * @requires OpenLayers/Feature/Vector.js * @requires OpenLayers/Ajax.js * @requires OpenLayers/Geometry.js + * + * Class: OpenLayers.Format.GML + * Read/Wite GML. + * + * Inherits from: + * - */ OpenLayers.Format.GML = OpenLayers.Class.create(); OpenLayers.Format.GML.prototype = OpenLayers.Class.inherit( OpenLayers.Format, { + /* + * APIProperty: featureNS + * Namespace used for feature attributes. Default matches the NS + * used by MapServer output. + */ featureNS: "http://mapserver.gis.umn.edu/mapserver", + /* + * APIProperty: featureName + * element name for features. Default is 'featureMember'. + */ featureName: "featureMember", + /* + * APIProperty: layerName + * Name of data layer. Default is 'features'. + */ + layerName: "features", + /** + * APIProperty: geometry + * Name of geometry element. + */ geometryName: "geometry", + /** + * APIProperty: collectionName + * Name of featureCollection element + */ collectionName: "FeatureCollection", + /** + * APIProperty: gmlns + * GML Namespace + */ gmlns: "http://www.opengis.net/gml", - /** - * Extract attributes from GML. Most of the time, - * this is a significant time usage, due to the need - * to recursively descend the XML to search for attributes. - * - * @type Boolean */ + /** + * APIProperty: extractAttributes + * {Boolean} Extract attributes from GML. Most of the time, this is a + * significant time usage, due to the need to recursively descend the XML + * to search for attributes. + */ extractAttributes: true, /** + * APIMethod: read * Read data from a string, and return a list of features. * - * @param {string|XMLNode} data data to read/parse. + * Parameters: + * data - {String} or {XMLNode} data to read/parse. */ read: function(data) { if (typeof data == "string") { @@ -73,10 +106,13 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: parseFeature * This function is the core of the GML parsing code in OpenLayers. * It creates the geometries that are then attached to the returned * feature, and calls parseAttributes() to get attribute data out. - * @param {DOMElement} xmlNode + + * Parameters: + * xmlNode - {} */ parseFeature: function(xmlNode) { var geom; @@ -178,10 +214,13 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: parseAttributes * recursive function parse the attributes of a GML node. * Searches for any child nodes which aren't geometries, * and gets their value. - * @param {DOMElement} xmlNode + * + * Parameters: + * xmlNode - {} */ parseAttributes: function(xmlNode) { var nodes = xmlNode.childNodes; @@ -208,10 +247,13 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: parsePolygonNode + * + * Parameters: + * xmlNode - {XMLNode} * - * @param {XMLNode} xmlNode - * - * @return {OpenLayers.Geometry.Polygon} polygon geometry + * Returns: + * {} polygon geometry */ parsePolygonNode: function(polygonNode) { var linearRings = OpenLayers.Ajax.getElementsByTagNameNS(polygonNode, @@ -231,12 +273,14 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: parseCoords * Extract Geographic coordinates from an XML node. - * @private - * @param {XMLNode} xmlNode - * - * @return an array of OpenLayers.Geometry.Point points. - * @type Array + * + * Parameters: + * xmlNode - {} + * + * Returns: + * An array of points. */ parseCoords: function(xmlNode) { var x, y, left, bottom, right, top, bounds; @@ -287,9 +331,12 @@ OpenLayers.Format.GML.prototype = }, /** - * Accept Feature Collection, and return a string. + * APIMethod: write + * Accept Feature Array, and return a string. * - * @param {Array} List of features to serialize into a string. + * Parameters: + * features - Array({}> List of features to + * serialize into a string. */ write: function(features) { var featureCollection = document.createElementNS("http://www.opengis.net/wfs", "wfs:" + this.collectionName); @@ -300,10 +347,14 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: createFeatureXML * Accept an OpenLayers.Feature.Vector, and build a geometry for it. - * - * @param {OpenLayers.Feature.Vector} feature - * @returns {DOMElement} + * + * Parameters: + * feature - {} + * + * Returns: + * {DOMElement} */ createFeatureXML: function(feature) { var geometryNode = this.buildGeometryNode(feature.geometry); @@ -326,10 +377,12 @@ OpenLayers.Format.GML.prototype = return featureNode; }, - /** + /** + * Method: buildGeometryNode * builds a GML file with a given geometry - * - * @param {OpenLayers.Geometry} geometry + * + * Parameters: + * geometry - {} */ buildGeometryNode: function(geometry) { // TBD test if geoserver can be given a Multi-geometry for a simple-geometry data store @@ -403,11 +456,15 @@ OpenLayers.Format.GML.prototype = }, /** + * Method: buildCoordinates * builds the coordinates XmlNode * ... * - * @param {OpenLayers.Geometry} geometry - * @return {XmlNode} created xmlNode + * Parameters: + * geometry - {} + * + * Returns: + * {XmlNode} created xmlNode */ buildCoordinatesNode: function(geometry) { var coordinatesNode = document.createElementNS(this.gmlns, "gml:coordinates"); diff --git a/lib/OpenLayers/Format/GeoRSS.js b/lib/OpenLayers/Format/GeoRSS.js index cdc7ddeff7..aef93a8ca4 100644 --- a/lib/OpenLayers/Format/GeoRSS.js +++ b/lib/OpenLayers/Format/GeoRSS.js @@ -3,23 +3,42 @@ * for the full text of the license. */ /** - * Write-only GeoRSS. * @requires OpenLayers/Format.js + * + * Class: OpenLayers.Format.GeoRSS + * Write-only GeoRSS. + * + * Inherits from: + * - */ OpenLayers.Format.GeoRSS = OpenLayers.Class.create(); OpenLayers.Format.GeoRSS.prototype = OpenLayers.Class.inherit( OpenLayers.Format, { + /** + * APIProperty: rssns + * RSS namespace to use. + */ rssns: "http://backend.userland.com/rss2", + /** + * APIProperty: featurens + * Feature Attributes namespace + */ featureNS: "http://mapserver.gis.umn.edu/mapserver", + /** + * APIProperty: georssns + * GeoRSS namespace to use. + */ georssns: "http://www.georss.org/georss", /** + * APIMethod: write * Accept Feature Collection, and return a string. * - * @param {Array} List of features to serialize into a string. + * Parameters: + * features - Array({}) List of features to serialize into a string. */ write: function(features) { var featureCollection = document.createElementNS(this.rssns, "rss"); @@ -29,11 +48,15 @@ OpenLayers.Format.GeoRSS.prototype = return featureCollection; }, - /** - * Accept an OpenLayers.Feature.Vector, and build a geometry for it. + /** + * Method: createFeatureXML + * Accept an , and build a geometry for it. * - * @param {OpenLayers.Feature.Vector} feature - * @returns DOMElement + * Parameters: + * feature - {} + * + * Returns: + * {DOMElement} */ createFeatureXML: function(feature) { var geometryNode = this.buildGeometryNode(feature.geometry); @@ -59,9 +82,11 @@ OpenLayers.Format.GeoRSS.prototype = }, /** + * Method: buildGeometryNode * builds a GeoRSS node with a given geometry * - * @param {OpenLayers.Geometry} geometry + * Parameters: + * geometry - {} */ buildGeometryNode: function(geometry) { var gml = ""; @@ -86,7 +111,13 @@ OpenLayers.Format.GeoRSS.prototype = } return gml; }, - + + /** + * Method: buildCoordinatesNode + * + * Parameters: + * geometry - {} + */ buildCoordinatesNode: function(geometry) { var points = null; diff --git a/lib/OpenLayers/Format/KML.js b/lib/OpenLayers/Format/KML.js index 83cf73a34d..d236451117 100644 --- a/lib/OpenLayers/Format/KML.js +++ b/lib/OpenLayers/Format/KML.js @@ -3,25 +3,33 @@ * for the full text of the license. */ /** - * Read only KML. * @requires OpenLayers/Format.js * @requires OpenLayers/Feature/Vector.js * @requires OpenLayers/Ajax.js + * + * Class: OpenLayers.Format.KML + * Read only KML. Largely Proof of Concept: does not support advanced Features, + * including Polygons. + * + * Inherits from: + * - */ OpenLayers.Format.KML = OpenLayers.Class.create(); OpenLayers.Format.KML.prototype = OpenLayers.Class.inherit( OpenLayers.Format, { - featureNS: "http://mapserver.gis.umn.edu/mapserver", - - collectionName: "FeatureCollection", - + /** + * APIProperty: kmlns + * KML Namespace to use. Defaults to 2.0 namespace. + */ kmlns: "http://earth.google.com/kml/2.0", /** + * APIMethod: read * Read data from a string, and return a list of features. * - * @param {string|XMLNode} data data to read/parse. + * Parameters: + * data - {string} or {XMLNode>} data to read/parse. */ read: function(data) { if (typeof data == "string") { @@ -43,10 +51,13 @@ OpenLayers.Format.KML.prototype = }, /** + * Method: parseFeature * This function is the core of the KML parsing code in OpenLayers. * It creates the geometries that are then attached to the returned * feature, and calls parseAttributes() to get attribute data out. - * @param {DOMElement} xmlNode + * + * Parameters: + * xmlNode - {} */ parseFeature: function(xmlNode) { var geom; @@ -87,10 +98,13 @@ OpenLayers.Format.KML.prototype = }, /** + * Method: parseAttributes * recursive function parse the attributes of a KML node. * Searches for any child nodes which aren't geometries, * and gets their value. - * @param {DOMElement} xmlNode + * + * Parameters: + * xmlNode - {} */ parseAttributes: function(xmlNode) { var nodes = xmlNode.childNodes; @@ -117,12 +131,14 @@ OpenLayers.Format.KML.prototype = }, /** + * Method: parseCoords * Extract Geographic coordinates from an XML node. - * @private - * @param {XMLNode} xmlNode + * + * Parameters: + * xmlNode - {} * - * @return an array of OpenLayers.Geometry.Point points. - * @type Array + * Returns: + * An array of points. */ parseCoords: function(xmlNode) { var p = []; diff --git a/lib/OpenLayers/Format/WFS.js b/lib/OpenLayers/Format/WFS.js index 4cbe83829c..1801ccb4ab 100644 --- a/lib/OpenLayers/Format/WFS.js +++ b/lib/OpenLayers/Format/WFS.js @@ -3,25 +3,36 @@ * for the full text of the license. */ /** - * Read/WRite WFS. * @requires OpenLayers/Format/GML.js + * + * Class: OpenLayers.Format.WFS + * Read/Write WFS. */ OpenLayers.Format.WFS = OpenLayers.Class.create(); OpenLayers.Format.WFS.prototype = OpenLayers.Class.inherit( OpenLayers.Format.GML, { + /** + * Property: layer + */ layer: null, + /** + * APIProperty: wfsns + */ wfsns: "http://www.opengis.net/wfs", /* + * Constructor: OpenLayers.Format.WFS * Create a WFS-T formatter. This requires a layer: that layer should * have two properties: geometry_column and typename. The parser * for this format is subclassed entirely from GML: There is a writer * only, which uses most of the code from the GML layer, and wraps * it in transactional elements. - * @param {Object} options - * @param {OpenLayers.Layer} layer + * + * Parameters: + * options - {Object} + * layer - {} */ initialize: function(options, layer) { @@ -39,10 +50,11 @@ OpenLayers.Format.WFS.prototype = }, /** - * write + * Method: write * Takes a feature list, and generates a WFS-T Transaction * - * @param {Array} + * Parameters: + * features - {Array} */ write: function(features) { @@ -64,7 +76,13 @@ OpenLayers.Format.WFS.prototype = } return transaction; }, - + + /** + * Method: createFeatureXML + * + * Parameters: + * feature - {} + */ createFeatureXML: function(feature) { var geometryNode = this.buildGeometryNode(feature.geometry); var geomContainer = document.createElementNS(this.featureNS, "feature:" + this.geometryName); @@ -85,10 +103,11 @@ OpenLayers.Format.WFS.prototype = }, /** - * insert + * Method: insert * Takes a feature, and generates a WFS-T Transaction "Insert" * - * @param {OpenLayers.Feature.Vector} feature + * Parameters: + * feature - {} */ insert: function(feature) { var insertNode = document.createElementNS(this.wfsns, 'wfs:Insert'); @@ -97,10 +116,11 @@ OpenLayers.Format.WFS.prototype = }, /** - * update + * Method: update * Takes a feature, and generates a WFS-T Transaction "Update" * - * @param {OpenLayers.Feature.Vector} feature + * Parameters: + * feature - {} */ update: function(feature) { if (!feature.fid) { alert("Can't update a feature for which there is no FID."); } @@ -130,10 +150,11 @@ OpenLayers.Format.WFS.prototype = }, /** - * delete + * Method: remove * Takes a feature, and generates a WFS-T Transaction "Delete" * - * @param {OpenLayers.Feature.Vector} feature + * Parameters: + * feature - {} */ remove: function(feature) { if (!feature.attributes.fid) { @@ -152,6 +173,10 @@ OpenLayers.Format.WFS.prototype = return deleteNode; }, + /** + * APIMethod: destroy + * Remove ciruclar ref to layer + */ destroy: function() { this.layer = null; }, diff --git a/lib/OpenLayers/Format/WKT.js b/lib/OpenLayers/Format/WKT.js index fb15b5059a..0a09e7b06e 100644 --- a/lib/OpenLayers/Format/WKT.js +++ b/lib/OpenLayers/Format/WKT.js @@ -3,15 +3,29 @@ * for the full text of the license. */ /** - * Read and write WKT. * @requires OpenLayers/Format.js + * + * Class: OpenLayers.Format.WKT + * Class for reading and writing Well-Known Text. Create a new instance + * with the constructor. + * + * Inherits from: + * - */ OpenLayers.Format.WKT = OpenLayers.Class.create(); OpenLayers.Format.WKT.prototype = OpenLayers.Class.inherit(OpenLayers.Format, { /** + * Constructor: OpenLayers.Format.WKT + * Create a new parser for WKT * + * Parameters: + * options - {Object} An optional object whose properties will be set on + * this instance + * + * Return: + * {} A new WKT parser. */ initialize: function(options) { this.regExes = { @@ -25,14 +39,18 @@ OpenLayers.Format.WKT.prototype = }, /** + * Method: read * Deserialize a WKT string and return an OpenLayers.Feature.Vector or an * array of OpenLayers.Feature.Vector. Supports WKT for POINT, MULTIPOINT, * LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, and * GEOMETRYCOLLECTION. - * @param {String} wkt A WKT string - * @returns {OpenLayers.Feature.Vector|Array} A feature or array of - * features for - * GEOMETRYCOLLECTION WKT. + * + * Parameters: + * wkt - {String} A WKT string + * + * Return: + * {|Array} A feature or array of features for + * GEOMETRYCOLLECTION WKT. */ read: function(wkt) { var features, type, str; @@ -48,10 +66,15 @@ OpenLayers.Format.WKT.prototype = }, /** + * Method: write * Serialize a feature or array of features into a WKT string. - * @param {OpenLayers.Feature.Vector|Array} features A feature or array of - * features - * @returns {String} The WKT string representation of the input geometries + * + * Parameters: + * features - {|Array} A feature or array of + * features + * + * Return: + * {String} The WKT string representation of the input geometries */ write: function(features) { var collection, geometry, type, data, isCollection; @@ -91,7 +114,7 @@ OpenLayers.Format.WKT.prototype = extract: { /** * Return a space delimited string of point coordinates. - * @param {OpenLayers.Geometry.Point} point + * @param {} point * @returns {String} A string of coordinates representing the point */ 'point': function(point) { @@ -100,7 +123,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a comma delimited string of point coordinates from a multipoint. - * @param {OpenLayers.Geometry.MultiPoint} multipoint + * @param {} multipoint * @returns {String} A string of point coordinate strings representing * the multipoint */ @@ -114,7 +137,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a comma delimited string of point coordinates from a line. - * @param {OpenLayers.Geometry.LineString} linestring + * @param {} linestring * @returns {String} A string of point coordinate strings representing * the linestring */ @@ -128,7 +151,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a comma delimited string of linestring strings from a multilinestring. - * @param {OpenLayers.Geometry.MultiLineString} multilinestring + * @param {} multilinestring * @returns {String} A string of of linestring strings representing * the multilinestring */ @@ -144,7 +167,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a comma delimited string of linear ring arrays from a polygon. - * @param {OpenLayers.Geometry.Polygon} polygon + * @param {} polygon * @returns {String} An array of linear ring arrays representing the polygon */ 'polygon': function(polygon) { @@ -159,7 +182,7 @@ OpenLayers.Format.WKT.prototype = /** * Return an array of polygon arrays from a multipolygon. - * @param {OpenLayers.Geometry.MultiPolygon} multipolygon + * @param {} multipolygon * @returns {Array} An array of polygon arrays representing * the multipolygon */ @@ -183,7 +206,7 @@ OpenLayers.Format.WKT.prototype = /** * Return point feature given a point WKT fragment. * @param {String} str A WKT fragment representing the point - * @returns {OpenLayers.Feature.Vector} A point feature + * @returns {} A point feature * @private */ 'point': function(str) { @@ -196,7 +219,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a multipoint feature given a multipoint WKT fragment. * @param {String} A WKT fragment representing the multipoint - * @returns {OpenLayers.Feature.Vector} A multipoint feature + * @returns {} A multipoint feature * @private */ 'multipoint': function(str) { @@ -213,7 +236,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a linestring feature given a linestring WKT fragment. * @param {String} A WKT fragment representing the linestring - * @returns {OpenLayers.Feature.Vector} A linestring feature + * @returns {} A linestring feature * @private */ 'linestring': function(str) { @@ -230,7 +253,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a multilinestring feature given a multilinestring WKT fragment. * @param {String} A WKT fragment representing the multilinestring - * @returns {OpenLayers.Feature.Vector} A multilinestring feature + * @returns {} A multilinestring feature * @private */ 'multilinestring': function(str) { @@ -249,7 +272,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a polygon feature given a polygon WKT fragment. * @param {String} A WKT fragment representing the polygon - * @returns {OpenLayers.Feature.Vector} A polygon feature + * @returns {} A polygon feature * @private */ 'polygon': function(str) { @@ -270,7 +293,7 @@ OpenLayers.Format.WKT.prototype = /** * Return a multipolygon feature given a multipolygon WKT fragment. * @param {String} A WKT fragment representing the multipolygon - * @returns {OpenLayers.Feature.Vector} A multipolygon feature + * @returns {} A multipolygon feature * @private */ 'multipolygon': function(str) { diff --git a/lib/OpenLayers/Geometry.js b/lib/OpenLayers/Geometry.js index 5b76428b1e..cf9cadcc3a 100644 --- a/lib/OpenLayers/Geometry.js +++ b/lib/OpenLayers/Geometry.js @@ -3,45 +3,58 @@ * for the full text of the license. */ /** - * @class * @requires OpenLayers/Format/WKT.js * @requires OpenLayers/Feature/Vector.js + * + * Class: OpenLayers.Geometry + * A Geometry is a description of a geographic object. Create an instance of + * this class with the constructor. This is a base class, + * typical geometry types are described by subclasses of this class. */ OpenLayers.Geometry = OpenLayers.Class.create(); OpenLayers.Geometry.prototype = { - /** @type String */ + /** + * Property: id + * {String} A unique identifier for this geometry. + */ id: null, - /** This is set when a Geometry is added as Component of another Geometry - * - * @type OpenLayers.Geometry */ + /** + * Property: parent + * {}This is set when a Geometry is added as component + * of another geometry + */ parent: null, - /** @type OpenLayers.Bounds */ + /** + * Property: bounds + * {} The bounds of this geometry + */ bounds: null, /** - * @constructor + * Constructor: OpenLayers.Geometry + * Creates a geometry object. */ initialize: function() { this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME+ "_"); }, /** - * + * Method: destroy + * Destroy this geometry. */ destroy: function() { this.id = null; - this.bounds = null; - }, /** * Set the bounds for this Geometry. * - * @param {OpenLayers.Bounds} object + * Parameters: + * object - {} */ setBounds: function(bounds) { if (bounds) { @@ -50,6 +63,7 @@ OpenLayers.Geometry.prototype = { }, /** + * Method: clearBounds * Nullify this components bounds and that of its parent as well. */ clearBounds: function() { @@ -60,10 +74,12 @@ OpenLayers.Geometry.prototype = { }, /** + * Method: extendBounds * Extend the existing bounds to include the new bounds. * If geometry's bounds is not yet set, then set a new Bounds. * - * @param {OpenLayers.Bounds} newBounds + * Parameters: + * newBounds - {} */ extendBounds: function(newBounds){ var bounds = this.getBounds(); @@ -75,10 +91,12 @@ OpenLayers.Geometry.prototype = { }, /** + * APIMethod: getBounds * Get the bounds for this Geometry. If bounds is not set, it * is calculated again, this makes queries faster. * - * @type OpenLayers.Bounds + * Return: + * {} */ getBounds: function() { if (this.bounds == null) { @@ -87,8 +105,9 @@ OpenLayers.Geometry.prototype = { return this.bounds; }, - /** Recalculate the bounds for the geometry. - * + /** + * APIMethod: calculateBounds + * Recalculate the bounds for the geometry. */ calculateBounds: function() { // @@ -97,15 +116,17 @@ OpenLayers.Geometry.prototype = { }, /** - * Note: This is only an approximation based on the bounds of the + * Method: atPoint + * Note - This is only an approximation based on the bounds of the * geometry. * - * @param {OpenLayers.LonLat} lonlat - * @param {float} toleranceLon Optional tolerance in Geometric Coords - * @param {float} toleranceLat Optional tolerance in Geographic Coords + * Parameters: + * lonlat - {} + * toleranceLon - {float} Optional tolerance in Geometric Coords + * toleranceLat - {float} Optional tolerance in Geographic Coords * - * @returns Whether or not the geometry is at the specified location - * @type Boolean + * Return: + * {Boolean} Whether or not the geometry is at the specified location */ atPoint: function(lonlat, toleranceLon, toleranceLat) { var atPoint = false; @@ -127,8 +148,12 @@ OpenLayers.Geometry.prototype = { }, /** - * @returns The length of the geometry - * @type float + * Method: getLength + * Calculate the length of this geometry. This method is defined in + * subclasses. + * + * Return: + * {Float} The length of the collection by summing its parts */ getLength: function() { //to be overridden by geometries that actually have a length @@ -137,8 +162,11 @@ OpenLayers.Geometry.prototype = { }, /** - * @returns The area of the geometry - * @type float + * Method: getArea + * Calculate the area of this geometry. This method is defined in subclasses. + * + * Return: + * {Float} The area of the collection by summing its parts */ getArea: function() { //to be overridden by geometries that actually have an area @@ -147,8 +175,11 @@ OpenLayers.Geometry.prototype = { }, /** - * @returns the Well-Known Text representation of a geometry - * @type String + * Method: toString + * Returns the Well-Known Text representation of a geometry + * + * Return: + * {String} Well-Known Text */ toString: function() { return OpenLayers.Format.WKT.prototype.write( @@ -156,6 +187,6 @@ OpenLayers.Geometry.prototype = { ); }, - /** @final @type String */ + /** @final @type String*/ CLASS_NAME: "OpenLayers.Geometry" }; diff --git a/lib/OpenLayers/Geometry/Collection.js b/lib/OpenLayers/Geometry/Collection.js index f02632b1ff..c395757d83 100644 --- a/lib/OpenLayers/Geometry/Collection.js +++ b/lib/OpenLayers/Geometry/Collection.js @@ -3,40 +3,50 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Geometry.js * + * Class: OpenLayers.Geometry.Collection * A Collection is exactly what it sounds like: A collection of different - * Geometries. These are stored in the local parameter "components" (which + * Geometries. These are stored in the local parameter (which * can be passed as a parameter to the constructor). * * As new geometries are added to the collection, they are NOT cloned. * When removing geometries, they need to be specified by reference (ie you * have to pass in the *exact* geometry to be removed). * - * The getArea() and getLength() functions here merely iterate through + * The and functions here merely iterate through * the components, summing their respective areas and lengths. - * - * @requires OpenLayers/Geometry.js + * + * Create a new instance with the constructor. + * + * Inerhits from: + * - */ OpenLayers.Geometry.Collection = OpenLayers.Class.create(); OpenLayers.Geometry.Collection.prototype = OpenLayers.Class.inherit( OpenLayers.Geometry, { - /** @type Array(OpenLayers.Geometry) */ + /** + * APIProperty: components + * {Array()} The component parts of this geometry + */ components: null, /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null value means the + * component types are not restricted. */ componentTypes: null, /** - * @constructor - * - * @param {Array(OpenLayers.Geometry)} components + * Constructor: OpenLayers.Geometry.Collection + * Creates a Geometry Collection -- a list of geoms. + * + * Parameters: + * components - {Array()} Optional array of geometries + * */ initialize: function (components) { OpenLayers.Geometry.prototype.initialize.apply(this, arguments); @@ -47,7 +57,8 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * + * APIMethod: destroy + * Destroy this geometry. */ destroy: function () { this.components.length = 0; @@ -55,8 +66,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @returns An exact clone of this collection - * @type OpenLayers.Geometry.Collection + * APIMethod: clone + * Clone this geometry. + * + * Return: + * {} An exact clone of this collection */ clone: function() { var geometry = eval("new " + this.CLASS_NAME + "()"); @@ -71,8 +85,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @returns the components of the geometry - * @type String + * Method: getComponentsString + * Get a string representing the components for this collection + * + * Return: + * {String} A string representation of the components of this geometry */ getComponentsString: function(){ var strings = []; @@ -82,9 +99,10 @@ OpenLayers.Geometry.Collection.prototype = return strings.join(","); }, - /** Recalculate the bounds by iterating through the components and - * calling calling extendBounds() on each item - * + /** + * APIMethod: calculateBounds + * Recalculate the bounds by iterating through the components and + * calling calling extendBounds() on each item. */ calculateBounds: function() { this.bounds = null; @@ -97,8 +115,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @param {Array(OpenLayers.Geometry)} components - * + * APIMethod: addComponents + * Add components to this geometry. + * + * Parameters: + * components - {Array()} An array of geometries to add */ addComponents: function(components){ if(!(components instanceof Array)) { @@ -110,16 +131,19 @@ OpenLayers.Geometry.Collection.prototype = }, /** + * Method: addComponent * Add a new component (geometry) to the collection. If this.componentTypes * is set, then the component class name must be in the componentTypes array. - * + * * The bounds cache is reset. * - * @param {OpenLayers.Geometry} component - * @param {int} index Index into the array to insert the component - * @type Boolean - * @return Component was successfully added - */ + * Parameters: + * component - {} A geometry to add + * index - {int} Optional index into the array to insert the component + * + * Return: + * {Boolean} The component geometry was successfully added + */ addComponent: function(component, index) { var added = false; if(component) { @@ -145,7 +169,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @param {Array(OpenLayers.Geometry)} components + * APIMethod: removeComponents + * Remove components from this geometry. + * + * Parameters: + * components - {Array()} The components to be removed */ removeComponents: function(components) { if(!(components instanceof Array)) { @@ -157,7 +185,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @param {OpenLayers.Geometry} component + * Method: removeComponent + * Remove a component from this geometry. + * + * Parameters: + * component - {} */ removeComponent: function(component) { @@ -169,8 +201,11 @@ OpenLayers.Geometry.Collection.prototype = }, /** - * @returns The length of the geometry - * @type float + * APIMethod: getLength + * Calculate the length of this geometry + * + * Return: + * {Float} The length of the geometry */ getLength: function() { var length = 0.0; @@ -180,10 +215,13 @@ OpenLayers.Geometry.Collection.prototype = return length; }, - /** Note how this function is overridden in Polygon - * - * @returns the area of the collection by summing its parts - * @type float + /** + * APIMethod: getArea + * Calculate the area of this geometry. Note how this function is overridden + * in . + * + * Return: + * {Float} The area of the collection by summing its parts */ getArea: function() { var area = 0.0; @@ -194,9 +232,12 @@ OpenLayers.Geometry.Collection.prototype = }, /** + * APIMethod: move * Moves a collection in place - * @param {Float} x - * @param {Float} y + * + * Parameters: + * x - {Float} The x-displacement (in map units) + * y - {Float} The y-displacement (in map units) */ move: function(x, y) { for(var i = 0; i < this.components.length; i++) { @@ -205,10 +246,14 @@ OpenLayers.Geometry.Collection.prototype = }, /** + * APIMethod: equals * Tests for equivalent geometries - * @param {OpenLayers.Geometry} - * @type Boolean - * @return The coordinates are equivalent + * + * Parameters: + * geometry - {} + * + * Return: + * {Boolean} The coordinates are equivalent */ equals: function(geometry) { var equivalent = true; @@ -228,6 +273,9 @@ OpenLayers.Geometry.Collection.prototype = return equivalent; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.Collection" }); diff --git a/lib/OpenLayers/Geometry/Curve.js b/lib/OpenLayers/Geometry/Curve.js index fd063520b8..567fb90270 100644 --- a/lib/OpenLayers/Geometry/Curve.js +++ b/lib/OpenLayers/Geometry/Curve.js @@ -3,30 +3,33 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Geometry/MultiPoint.js * + * Class: OpenLayers.Geometry.Curve * A Curve is a MultiPoint, whose points are assumed to be connected. To * this end, we provide a "getLength()" function, which iterates through * the points, summing the distances between them. - * - * @requires OpenLayers/Geometry/MultiPoint.js + * + * Inherits: + * - */ OpenLayers.Geometry.Curve = OpenLayers.Class.create(); OpenLayers.Geometry.Curve.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.MultiPoint, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null + * value means the component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.Point"], /** - * @constructor - * - * @param {Array(OpenLayers.Geometry.Point)} points + * Constructor: OpenLayers.Geometry.Curve + * + * Parameters: + * point - {Array()} */ initialize: function(points) { OpenLayers.Geometry.MultiPoint.prototype.initialize.apply(this, @@ -34,8 +37,10 @@ OpenLayers.Geometry.Curve.prototype = }, /** - * @returns The length of the curve - * @type float + * APIMethod: getLength + * + * Return: + * {Float} The length of the curve */ getLength: function() { var length = 0.0; diff --git a/lib/OpenLayers/Geometry/LineString.js b/lib/OpenLayers/Geometry/LineString.js index b6774d1c30..dfd549c0a3 100644 --- a/lib/OpenLayers/Geometry/LineString.js +++ b/lib/OpenLayers/Geometry/LineString.js @@ -3,30 +3,39 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Geometry/Curve.js * + * Class: OpenLayers.Geometry.LineString * A LineString is a Curve which, once two points have been added to it, can * never be less than two points long. - * - * @requires OpenLayers/Geometry/Curve.js + * + * Inherits from: + * - */ OpenLayers.Geometry.LineString = OpenLayers.Class.create(); OpenLayers.Geometry.LineString.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.Curve, { /** - * @constructor - * - * @param {Array(OpenLayers.Geometry.Point)} points + * Constructor: OpenLayers.Geometry.LineString + * Create a new LineString geometry + * + * Parameters: + * points - {Array()} An array of points used to + * generate the linestring + * */ initialize: function(points) { OpenLayers.Geometry.Curve.prototype.initialize.apply(this, arguments); }, - /** Only allows removal of a point if there are three or more points in - * the linestring. (otherwise the result would be just a single point) - * - * @param {OpenLayers.Geometry.Point} point + /** + * APIMethod: removeComponent + * Only allows removal of a point if there are three or more points in + * the linestring. (otherwise the result would be just a single point) + * + * Parameters: + * point - {} The point to be removed */ removeComponent: function(point) { if ( this.components && (this.components.length > 2)) { @@ -35,6 +44,9 @@ OpenLayers.Geometry.LineString.prototype = } }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.LineString" }); diff --git a/lib/OpenLayers/Geometry/LinearRing.js b/lib/OpenLayers/Geometry/LinearRing.js index f9ce479647..94cdc58237 100644 --- a/lib/OpenLayers/Geometry/LinearRing.js +++ b/lib/OpenLayers/Geometry/LinearRing.js @@ -3,7 +3,9 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Geometry/LineString.js + * + * Class: OpenLayers.Geometry.LinearRing * * A Linear Ring is a special LineString which is closed. It closes itself * automatically on every addPoint/removePoint by adding a copy of the first @@ -12,29 +14,31 @@ * Also, as it is the first in the line family to close itself, a getArea() * function is defined to calculate the enclosed area of the linearRing * - * @requires OpenLayers/Geometry/LineString.js + * Inherits: + * - */ OpenLayers.Geometry.LinearRing = OpenLayers.Class.create(); OpenLayers.Geometry.LinearRing.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.LineString, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null + * value means the component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.Point"], /** + * Constructor: OpenLayers.Geometry.LinearRing * Linear rings are constructed with an array of points. This array - * can represent a closed or open ring. If the ring is open (the last - * point does not equal the first point), the constructor will close - * the ring. If the ring is already closed (the last point does equal - * the first point), it will be left closed. + * can represent a closed or open ring. If the ring is open (the last + * point does not equal the first point), the constructor will close + * the ring. If the ring is already closed (the last point does equal + * the first point), it will be left closed. * - * @constructor - * @param {Array(OpenLayers.Geometry.Point)} points + * Parameters: + * points - {Array()} points */ initialize: function(points) { OpenLayers.Geometry.LineString.prototype.initialize.apply(this, @@ -42,17 +46,21 @@ OpenLayers.Geometry.LinearRing.prototype = }, /** + * APIMethod: addComponent * Adds a point to geometry components. If the point is to be added to - * the end of the components array and it is the same as the last point - * already in that array, the duplicate point is not added. This has the - * effect of closing the ring if it is not already closed, and doing the - * right thing if it is already closed. This behavior can be overridden - * by calling the method with a non-null index as the second argument. + * the end of the components array and it is the same as the last point + * already in that array, the duplicate point is not added. This has + * the effect of closing the ring if it is not already closed, and + * doing the right thing if it is already closed. This behavior can + * be overridden by calling the method with a non-null index as the + * second argument. * - * @param {OpenLayers.Geometry.Point} point - * @param {int} index Index into the array to insert the component - * @type Boolean - * @return Point was successfully added + * Parameter: + * point - {} + * index - {Integer} Index into the array to insert the component + * + * Return: + * {Boolean} Was the Point successfully added? */ addComponent: function(point, index) { var added = false; @@ -78,9 +86,11 @@ OpenLayers.Geometry.LinearRing.prototype = }, /** - * Removes a point from geometry components + * APIMethod: removeComponent + * Removes a point from geometry components. * - * @param {OpenLayers.Geometry.Point} point + * Parameters: + * point - {} */ removeComponent: function(point) { if (this.components.length > 4) { @@ -100,11 +110,13 @@ OpenLayers.Geometry.LinearRing.prototype = } }, - /** Note: The area is positive if the ring is oriented CW, otherwise + /** + * APIMethod: getArea + * Note - The area is positive if the ring is oriented CW, otherwise * it will be negative. * - * @returns The signed area for a ring. - * @type float + * Return: + * {Float} The signed area for a ring. */ getArea: function() { var area = 0.0; diff --git a/lib/OpenLayers/Geometry/MultiLineString.js b/lib/OpenLayers/Geometry/MultiLineString.js index e806617886..b225f5bdde 100644 --- a/lib/OpenLayers/Geometry/MultiLineString.js +++ b/lib/OpenLayers/Geometry/MultiLineString.js @@ -3,34 +3,44 @@ * for the full text of the license. */ /** - * @class - * - * A MultiLineString is a collection of LineStrings - * * @requires OpenLayers/Geometry/Collection.js + * + * Class: OpenLayers.Geometry.MultiLineString + * A MultiLineString is a geometry with multiple + * components. + * + * Inherits from: + * - + * - */ OpenLayers.Geometry.MultiLineString = OpenLayers.Class.create(); OpenLayers.Geometry.MultiLineString.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.Collection, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null value means the + * component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.LineString"], /** - * @constructor + * Constructor: OpenLayers.Geometry.MultiLineString + * Constructor for a MultiLineString Geometry. + * + * Parameters: + * components - {Array(OpenLayers.Geometry.LineString)} * - * @param {Array(OpenLayers.Geometry.LineString)} components */ initialize: function(components) { OpenLayers.Geometry.Collection.prototype.initialize.apply(this, arguments); }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.MultiLineString" }); diff --git a/lib/OpenLayers/Geometry/MultiPoint.js b/lib/OpenLayers/Geometry/MultiPoint.js index 16b195b1c1..e5eaeb8457 100644 --- a/lib/OpenLayers/Geometry/MultiPoint.js +++ b/lib/OpenLayers/Geometry/MultiPoint.js @@ -3,28 +3,37 @@ * for the full text of the license. */ /** - * @class - * - * MultiPoint is a collection of Points. - * * @requires OpenLayers/Geometry/Collection.js + * + * Class: OpenLayers.Geometry.MultiPoint + * MultiPoint is a collection of Points. Create a new instance with the + * constructor. + * + * Inherits from: + * - + * - */ OpenLayers.Geometry.MultiPoint = OpenLayers.Class.create(); OpenLayers.Geometry.MultiPoint.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.Collection, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null value means the + * component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.Point"], /** - * @constructor + * Constructor: OpenLayers.Geometry.MultiPoint + * Create a new MultiPoint Geometry * - * @param {Array(OpenLayers.Geometry.Point)} components + * Parameters: + * components - Array({}) + * + * Return: + * {} */ initialize: function(components) { OpenLayers.Geometry.Collection.prototype.initialize.apply(this, @@ -32,23 +41,31 @@ OpenLayers.Geometry.MultiPoint.prototype = }, /** - * Wrapper for addComponent() - * - * @param {OpenLayers.Geometry.Point} point - * @param {int} index + * APIMethod: addPoint + * Wrapper for + * + * Parameters: + * point - {} Point to be added + * index - {Integer} Optional index */ addPoint: function(point, index) { this.addComponent(point, index); }, /** - * Wrapper for removeComponent() + * APIMethod: removePoint + * Wrapper for * - * @param {OpenLayers.Geometry.Point} point + * Parameters: + * point - {} Point to be removed */ removePoint: function(point){ this.removeComponent(point); }, - /** @final @type String */ + + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.MultiPoint" }); diff --git a/lib/OpenLayers/Geometry/MultiPolygon.js b/lib/OpenLayers/Geometry/MultiPolygon.js index e00cd7240b..42be693e6c 100644 --- a/lib/OpenLayers/Geometry/MultiPolygon.js +++ b/lib/OpenLayers/Geometry/MultiPolygon.js @@ -3,34 +3,45 @@ * for the full text of the license. */ /** - * @class - * - * MultiPolygon is a collection of Polygons. - * * @requires OpenLayers/Geometry/Collection.js + * + * Class: OpenLayers.Geometry.MultiPolygon + * MultiPolygon is a geometry with multiple + * components. Create a new instance with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Geometry.MultiPolygon = OpenLayers.Class.create(); OpenLayers.Geometry.MultiPolygon.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.Collection, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null value means the + * component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.Polygon"], /** - * @constructor - * - * @param {Array(OpenLayers.Geometry.Polygon)} components - */ + * Constructor: OpenLayers.Geometry.MultiPolygon + * Create a new MultiPolygon geometry + * + * Parameters: + * components - {Array()} An array of polygons + * used to generate the MultiPolygon + * + */ initialize: function(components) { OpenLayers.Geometry.Collection.prototype.initialize.apply(this, arguments); }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.MultiPolygon" }); diff --git a/lib/OpenLayers/Geometry/Point.js b/lib/OpenLayers/Geometry/Point.js index 929ffcbe1c..62e4829abb 100644 --- a/lib/OpenLayers/Geometry/Point.js +++ b/lib/OpenLayers/Geometry/Point.js @@ -3,25 +3,38 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Geometry.js + * + * Class: OpenLayers.Geometry.Point + * Point geometry class. + * + * Inherits from: + * - */ OpenLayers.Geometry.Point = OpenLayers.Class.create(); OpenLayers.Geometry.Point.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry, { - /** @type float */ + /** + * APIProperty: x + * {float} + */ x: null, - /** @type float */ + /** + * APIProperty: y + * {float} + */ y: null, /** - * @constructor + * Constructor: OpenLayers.Geometry.Point + * Construct a point geometry. * - * @param {float} x - * @param {float} y + * Parameters: + * x - {float} + * y - {float} + * */ initialize: function(x, y) { OpenLayers.Geometry.prototype.initialize.apply(this, arguments); @@ -31,8 +44,10 @@ OpenLayers.Geometry.Point.prototype = }, /** - * @returns An exact clone of this OpenLayers.Geometry.Point - * @type OpenLayers.Geometry.Point + * APIMethod: clone + * + * Return: + * {} An exact clone of this OpenLayers.Geometry.Point */ clone: function(obj) { if (obj == null) { @@ -45,8 +60,9 @@ OpenLayers.Geometry.Point.prototype = return obj; }, - /** Create a new Bounds based on the lon/lat - * + /** + * Method: calculateBounds + * Create a new Bounds based on the lon/lat */ calculateBounds: function () { this.bounds = new OpenLayers.Bounds(this.x, this.y, @@ -54,7 +70,10 @@ OpenLayers.Geometry.Point.prototype = }, /** - * @param {OpenLayers.Geometry.Point} point + * APIMethod: distanceTo + * + * Parameters: + * point - {} */ distanceTo: function(point) { var distance = 0.0; @@ -69,12 +88,16 @@ OpenLayers.Geometry.Point.prototype = }, /** - * @param {OpenLayers.Geometry} xy - * @returns Boolean value indicating whether the passed-in - * OpenLayers.Geometryobject has the same components as this + * APIMethod: equals + * + * Parameters: + * xy - {} + * + * Return: + * {Boolean} Boolean value indicating whether the passed-in + * {} object has the same components as this * note that if ll passed in is null, returns false * - * @type bool */ equals:function(geom) { var equals = false; @@ -86,24 +109,31 @@ OpenLayers.Geometry.Point.prototype = }, /** - * @return Shortened String representation of Point object. + * Method: toShortString + * + * Return: + * {String} Shortened String representation of Point object. * (ex. "5, 42") - * @type String */ toShortString: function() { return (this.x + ", " + this.y); }, /** + * APIMethod: move * Moves a point in place - * @param {Float} x - * @param {Float} y + * + * Parameters: + * x - {Float} + * y - {Float} */ move: function(x, y) { this.x = this.x + x; this.y = this.y + y; }, - /** @final @type String */ + /** Constant: CLASS_NAME + * {String} Name of this class + */ CLASS_NAME: "OpenLayers.Geometry.Point" }); diff --git a/lib/OpenLayers/Geometry/Polygon.js b/lib/OpenLayers/Geometry/Polygon.js index cf496c0014..e015b9eb3c 100644 --- a/lib/OpenLayers/Geometry/Polygon.js +++ b/lib/OpenLayers/Geometry/Polygon.js @@ -3,42 +3,49 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Geometry/Collection.js * + * Class: OpenLayers.Geometry.Polygon * Polygon is a collection of Geometry.LinearRings. * - * The first ring (this.component[0])is the outer bounds of the polygon and - * all subsequent rings (this.component[1-n]) are internal holes. - * - * @requires OpenLayers/Geometry/Collection.js + * Inherits from: + * - + * - */ OpenLayers.Geometry.Polygon = OpenLayers.Class.create(); OpenLayers.Geometry.Polygon.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry.Collection, { /** - * An array of class names representing the types of components that - * the collection can include. A null value means the component types - * are not restricted. - * @type Array(String) + * Property: componentTypes + * {Array(String)} An array of class names representing the types of + * components that the collection can include. A null value means the + * component types are not restricted. */ componentTypes: ["OpenLayers.Geometry.LinearRing"], /** - * @constructor + * Constructor: OpenLayers.Geometry.Polygon + * Constructor for a Polygon geometry. + * The first ring (this.component[0])is the outer bounds of the polygon and + * all subsequent rings (this.component[1-n]) are internal holes. * - * @param {Array(OpenLayers.Geometry.LinearRing)} + * + * Parameters: + * components - Array({}) */ initialize: function(components) { OpenLayers.Geometry.Collection.prototype.initialize.apply(this, arguments); }, - /** Calculated by subtracting the areas of the internal holes from the + /** + * APIMethod: getArea + * Calculated by subtracting the areas of the internal holes from the * area of the outer hole. * - * @returns The area of the geometry - * @type float + * Return: + * {float} The area of the geometry */ getArea: function() { var area = 0.0; @@ -51,6 +58,9 @@ OpenLayers.Geometry.Polygon.prototype = return area; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Geometry.Polygon" }); diff --git a/lib/OpenLayers/Geometry/Rectangle.js b/lib/OpenLayers/Geometry/Rectangle.js index 63c312ab22..9b4a596b53 100644 --- a/lib/OpenLayers/Geometry/Rectangle.js +++ b/lib/OpenLayers/Geometry/Rectangle.js @@ -3,35 +3,50 @@ * for the full text of the license. */ /** - * @class - * - * A Rectangle is a simple geometry. It is specified by a a point (x and y) - * and dimensions (width and height), all of which are directly accessible as - * properties. - * * @requires OpenLayers/Geometry.js + * + * Class: OpenLayers.Geometry.Rectangle + * A Rectangle is a simple geometry. It is specified by a a point (x and y) + * and dimensions (width and height), all of which are directly accessible + * as properties. + * + * Inherits: + * - */ OpenLayers.Geometry.Rectangle = OpenLayers.Class.create(); OpenLayers.Geometry.Rectangle.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry, { - /** @type float */ + /** + * Property: x + * {Float} + */ x: null, - /** @type float */ + /** + * Property: y + * {Float} + */ y: null, - /** @type float */ + /** + * Property: width + * {Float} + */ width: null, - /** @type float */ + /** + * Property: height + * {Float} + */ height: null, /** - * @constructor - * - * @param {array} points + * Constructor: OpenLayers.Geometry.Rectangle + * + * Parameters: + * points - {Array(} */ initialize: function(x, y, width, height) { OpenLayers.Geometry.prototype.initialize.apply(this, arguments); @@ -44,7 +59,8 @@ OpenLayers.Geometry.Rectangle.prototype = }, /** - * + * Method: calculateBounds + * Recalculate the bounds for the geometry. */ calculateBounds: function() { this.bounds = new OpenLayers.Bounds(this.x, this.y, @@ -54,8 +70,10 @@ OpenLayers.Geometry.Rectangle.prototype = /** - * @returns The length of the geometry - * @type float + * APIMethod: getLength + * + * Return: + * {Float} The length of the geometry */ getLength: function() { var length = (2 * this.width) + (2 * this.height); @@ -63,8 +81,10 @@ OpenLayers.Geometry.Rectangle.prototype = }, /** - * @returns The area of the geometry - * @type float + * APIMethod: getArea + * + * Return: + * {Float} The area of the geometry */ getArea: function() { var area = this.width * this.height; diff --git a/lib/OpenLayers/Geometry/Surface.js b/lib/OpenLayers/Geometry/Surface.js index d7a8aa756a..bf39e05595 100644 --- a/lib/OpenLayers/Geometry/Surface.js +++ b/lib/OpenLayers/Geometry/Surface.js @@ -3,23 +3,22 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Geometry.js + * + * Class: OpenLayers.Geometry.Surface */ OpenLayers.Geometry.Surface = OpenLayers.Class.create(); OpenLayers.Geometry.Surface.prototype = OpenLayers.Class.inherit(OpenLayers.Geometry, { /** - * @constructor + * Constructor: OpenLayers.Geometry.Surface * */ initialize: function() { OpenLayers.Geometry.prototype.initialize.apply(this, arguments); }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Geometry.Surface" }); diff --git a/lib/OpenLayers/Handler.js b/lib/OpenLayers/Handler.js index a04bd0c7d0..2fe8d68e57 100644 --- a/lib/OpenLayers/Handler.js +++ b/lib/OpenLayers/Handler.js @@ -4,11 +4,10 @@ /** + * Class: OpenLayers.Handler * Base class to construct a higher-level handler for event sequences. * Handlers are created by controls, which ultimately have the responsibility * of making changes to the map. - * - * @class */ OpenLayers.Handler = OpenLayers.Class.create(); @@ -19,42 +18,44 @@ OpenLayers.Handler.MOD_ALT = 4; OpenLayers.Handler.prototype = { /** - * @type String - * @private + * Property: id + * *Private*. {String} */ id: null, /** - * The control that initialized this handler. - * @type OpenLayers.Control - * @private + * Property: control + * *Private*. {}. The control that initialized this + * handler. */ control: null, /** - * @type OpenLayers.Map - * @private + * Property: map + * *Private*. {} */ map: null, /** - * @type integer + * Property: keyMask + * {Integer} */ -// keyMask: OpenLayers.Handler.MOD_NONE, keyMask: null, /** - * @type Boolean - * @private + * Property: active + * *Private*. {Boolean} */ active: false, /** - * @constructor + * Constructor: OpenLayers.Handler + * Construct a handler. * - * @param {OpenLayers.Control} control - * @param {Object} callbacks A hash of callback functions - * @param {Object} options + * Parameters: + * control - {} + * callbacks - {Object} A hash of callback functions + * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Util.extend(this, options); @@ -69,10 +70,16 @@ OpenLayers.Handler.prototype = { this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_"); }, + /** + * Method: setMap + */ setMap: function (map) { this.map = map; }, + /** + * Method: checkModifiers + */ checkModifiers: function (evt) { if(this.keyMask == null) { return true; @@ -89,9 +96,11 @@ OpenLayers.Handler.prototype = { }, /** + * Method: activate * Turn on the handler. Returns false if the handler was already active. - * - * @type {Boolean} + * + * Return: + * {Boolean} */ activate: function() { if(this.active) { @@ -109,9 +118,10 @@ OpenLayers.Handler.prototype = { }, /** + * Method: deactivate * Turn off the handler. Returns false if the handler was already inactive. * - * @type {Boolean} + * Return: {Boolean} */ deactivate: function() { if(!this.active) { @@ -129,6 +139,7 @@ OpenLayers.Handler.prototype = { }, /** + * Method: callback * trigger the control's named callback with the given arguments */ callback: function (name, args) { @@ -138,6 +149,7 @@ OpenLayers.Handler.prototype = { }, /** + * Method: register * register an event on the map */ register: function (name, method) { @@ -146,6 +158,7 @@ OpenLayers.Handler.prototype = { }, /** + * Method: unregister * unregister an event from the map */ unregister: function (name, method) { @@ -153,7 +166,7 @@ OpenLayers.Handler.prototype = { }, /** - * + * Method: destroy */ destroy: function () { // eliminate circular references diff --git a/lib/OpenLayers/Handler/Box.js b/lib/OpenLayers/Handler/Box.js index f7509f236b..bacde291fa 100644 --- a/lib/OpenLayers/Handler/Box.js +++ b/lib/OpenLayers/Handler/Box.js @@ -3,28 +3,34 @@ * for the full text of the license. */ /** + * @requires OpenLayers/Handler.js + * @requires OpenLayers/Handler/Drag.js + * + * Class: OpenLayers.Handler.Box * Handler for dragging a rectangle across the map. Box is displayed * on mouse down, moves on mouse move, and is finished on mouse up. - * - * @class - * @requires OpenLayers/Handler.js + * + * Inherits from: + * - */ OpenLayers.Handler.Box = OpenLayers.Class.create(); OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, { - /** - * @type OpenLayers.Handler.Drag - */ - dragHandler: null, + /** + * Property: dragHandler + * {} + */ + dragHandler: null, /** - * @constructor + * Constructor: OpenLayers.Handler.Box * - * @param {OpenLayers.Control} control - * @param {Object} callbacks An object containing a single function to be + * Parameters: + * control - {} + * callbacks - {Object} An object containing a single function to be * called when the drag operation is finished. * The callback should expect to recieve a single * argument, the point geometry. - * @param {Object} options + * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Handler.prototype.initialize.apply(this, arguments); @@ -38,6 +44,9 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, this, callbacks, {keyMask: this.keyMask}); }, + /** + * Method: setMap + */ setMap: function (map) { OpenLayers.Handler.prototype.setMap.apply(this, arguments); if (this.dragHandler) { @@ -46,7 +55,10 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, }, /** - * @param {Event} evt + * Method: startBox + * + * Parameters: + * evt - {Event} */ startBox: function (xy) { this.zoomBox = OpenLayers.Util.createDiv('zoomBox', @@ -67,6 +79,7 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, }, /** + * Method: moveBox */ moveBox: function (xy) { var deltaX = Math.abs(this.dragHandler.start.x - xy.x); @@ -82,6 +95,7 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, }, /** + * Method: endBox */ endBox: function(end) { var result; @@ -105,6 +119,7 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, }, /** + * Method: removeBox * Remove the zoombox from the screen and nullify our reference to it. */ removeBox: function() { @@ -112,6 +127,9 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, this.zoomBox = null; }, + /** + * Method: activate + */ activate: function () { if (OpenLayers.Handler.prototype.activate.apply(this, arguments)) { this.dragHandler.activate(); @@ -121,6 +139,9 @@ OpenLayers.Handler.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, } }, + /** + * Method: deactivate + */ deactivate: function () { if (OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { this.dragHandler.deactivate(); diff --git a/lib/OpenLayers/Handler/Drag.js b/lib/OpenLayers/Handler/Drag.js index b3c7661b4e..28144a5e51 100644 --- a/lib/OpenLayers/Handler/Drag.js +++ b/lib/OpenLayers/Handler/Drag.js @@ -3,54 +3,62 @@ * for the full text of the license. */ /** - * Handler for dragging a rectangle across the map. Drag is displayed - * on mouse down, moves on mouse move, and is finished on mouse up. - * - * @class * @requires OpenLayers/Handler.js * @requires OpenLayers/Events.js + * + * Class: OpenLayers.Handler.Drag */ OpenLayers.Handler.Drag = OpenLayers.Class.create(); OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, { /** - * When a mousedown event is received, we want to record it, but not set - * 'dragging' until the mouse moves after starting. - * - * @type Boolean + * Property: started + * {Boolean} When a mousedown event is received, we want to record it, but + * not set 'dragging' until the mouse moves after starting. **/ started: false, - /** @type Boolean **/ - dragging: false, + /** + * Property: dragging + * {Boolean} + */ + dragging: false, - /** @type OpenLayers.Pixel **/ - start: null, + /** + * Property: start + * {} + */ + start: null, /** - * @type Function - * @private + * Property: oldOnselectstart + * *Private*. {Function} */ oldOnselectstart: null, /** - * @constructor - * - * @param {OpenLayers.Control} control - * @param {Object} callbacks An object containing a single function to be + * Constructor: OpenLayers.Handler.Drag + * Returns OpenLayers.Handler.Drag + * + * Parameters: + * control - {} + * callbacks - {Object} An object containing a single function to be * called when the drag operation is finished. * The callback should expect to recieve a single * argument, the point geometry. - * @param {Object} options + * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Handler.prototype.initialize.apply(this, arguments); }, /** + * Method: mousedown * Handle mousedown events - * @param {Event} evt - * @type Boolean - * @return Should the event propagate + * + * Parameters: + * evt - {Event} + * + * Return: {Boolean} Should the event propagate */ mousedown: function (evt) { if (this.checkModifiers(evt) && OpenLayers.Event.isLeftClick(evt)) { @@ -67,10 +75,13 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: mousemove * Handle mousemove events - * @param {Event} evt - * @type Boolean - * @return Should the event propagate + * + * Parameters: + * evt - {Event} + * + * Return: {Boolean} Should the event propagate */ mousemove: function (evt) { if (this.started) { @@ -85,10 +96,13 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: mouseup * Handle mouseup events - * @param {Event} evt - * @type Boolean - * @return Should the event propagate + * + * Parameters: + * evt - {Event} + * + * Return: {Boolean} Should the event propagate */ mouseup: function (evt) { if (this.started) { @@ -102,10 +116,13 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: mouseout * Handle mouseout events - * @param {Event} evt - * @type Boolean - * @return Should the event propagate + * + * Parameters: + * evt - {Event} + * + * Return: {Boolean} Should the event propagate */ mouseout: function (evt) { if (this.started && OpenLayers.Util.mouseLeft(evt, this.map.div)) { @@ -122,12 +139,15 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: click * The drag handler captures the click event. If something else registers * for clicks on the same element, its listener will not be called after a * drag. - * @param {Event} evt - * @type Boolean - * @return Should the event propagate + * + * Parameters: + * evt - {Event} + * + * Return: {Boolean} Should the event propagate */ click: function (evt) { // throw away the first left click event that happens after a mouse up @@ -140,9 +160,11 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: activate * Activate the handler. - * @type Boolean - * @return Was activation successful. Returns false if already active. + * + * Return: {Boolean} Was activation successful. Returns false if already + * active. */ activate: function() { if(OpenLayers.Handler.prototype.activate.apply(this, arguments)) { @@ -154,9 +176,11 @@ OpenLayers.Handler.Drag.prototype = OpenLayers.Class.inherit( OpenLayers.Handler }, /** + * Method: deactivate * Deactivate the handler. - * @type Boolean - * @return Was deactivation successful. Returns false if not already active. + * + * Return: {Boolean} Was deactivation successful. Returns false if already + * active. */ deactivate: function() { if(OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { diff --git a/lib/OpenLayers/Handler/Feature.js b/lib/OpenLayers/Handler/Feature.js index dafd0297dc..0a68c2c995 100644 --- a/lib/OpenLayers/Handler/Feature.js +++ b/lib/OpenLayers/Handler/Feature.js @@ -4,37 +4,40 @@ /** + * @requires OpenLayers/Handler.js + * + * Class: OpenLayers.Handler.Feature * Handler to respond to mouse events related to a drawn feature. * Callbacks will be called for over, move, out, up, and down (corresponding * to the equivalent mouse events). - * - * @class - * @requires OpenLayers/Handler.js */ OpenLayers.Handler.Feature = OpenLayers.Class.create(); OpenLayers.Handler.Feature.prototype = OpenLayers.Class.inherit(OpenLayers.Handler, { /** - * @type {Int} + * Property: layerIndex + * {Int} */ layerIndex: null, /** - * @type {OpenLayers.Feature.Vector} + * Property: feature + * {} */ feature: null, /** - * @constructor + * Constructor: OpenLayers.Handler.Feature * - * @param {OpenLayers.Control} control - * @param {Array} layers List of OpenLayers.Layer.Vector - * @param {Array} callbacks An object with a 'over' property whos value is + * Parameters: + * control - {} + * layers - {Array} List of OpenLayers.Layer.Vector + * callbacks - {Array} An object with a 'over' property whos value is * a function to be called when the mouse is over * a feature. The callback should expect to recieve * a single argument, the feature. - * @param {Object} options + * options - {Object} */ initialize: function(control, layer, callbacks, options) { OpenLayers.Handler.prototype.initialize.apply(this, [control, callbacks, options]); @@ -42,9 +45,11 @@ OpenLayers.Handler.Feature.prototype = }, /** + * Method: mousedown * Handle mouse down. Call the "down" callback if down on a feature. * - * @param {Event} evt + * Parameters: + * evt - {Event} */ mousedown: function(evt) { var selected = this.select('down', evt); @@ -52,11 +57,13 @@ OpenLayers.Handler.Feature.prototype = }, /** + * Method: mousemove * Handle mouse moves. Call the "move" callback if moving over a feature. * Call the "over" callback if moving over a feature for the first time. * Call the "out" callback if moving off of a feature. * - * @param {Event} evt + * Parameters: + * evt - {Event} */ mousemove: function(evt) { this.select('move', evt); @@ -64,9 +71,11 @@ OpenLayers.Handler.Feature.prototype = }, /** - * Handle mouse moves. Call the "up" callback if up on a feature. + * Method: mouseup + * Handle mouse up. Call the "up" callback if up on a feature. * - * @param {Event} evt + * Parameters: + * evt - {Event} */ mouseup: function(evt) { var selected = this.select('up', evt); @@ -74,11 +83,13 @@ OpenLayers.Handler.Feature.prototype = }, /** + * Method: dblclick * Capture double-clicks. Let the event continue propagating if the * double-click doesn't hit a feature. Otherwise call the dblclick * callback. * - * @param {Event} evt + * Parameters: + * evt - {Event} */ dblclick: function(evt) { var selected = this.select('dblclick', evt); @@ -86,10 +97,14 @@ OpenLayers.Handler.Feature.prototype = }, /** + * Method: select * Trigger the appropriate callback if a feature is under the mouse. * - * @param {String} type Callback key - * @type {Boolean} A feature was selected + * Parameters: + * type - {String} Callback key + * + * Return: + * {Boolean} A feature was selected */ select: function(type, evt) { var feature = this.layer.getFeatureFromEvent(evt); @@ -118,9 +133,10 @@ OpenLayers.Handler.Feature.prototype = }, /** + * Method: activate * Turn on the handler. Returns false if the handler was already active. * - * @type {Boolean} + * Return: {Boolean} */ activate: function() { if(OpenLayers.Handler.prototype.activate.apply(this, arguments)) { @@ -133,9 +149,10 @@ OpenLayers.Handler.Feature.prototype = }, /** - * Turn onf the handler. Returns false if the handler was already active. + * Method: activate + * Turn of the handler. Returns false if the handler was already active. * - * @type {Boolean} + * Returns: {Boolean} */ deactivate: function() { if(OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { diff --git a/lib/OpenLayers/Handler/Keyboard.js b/lib/OpenLayers/Handler/Keyboard.js index 2ac61ad5f0..6f52034801 100644 --- a/lib/OpenLayers/Handler/Keyboard.js +++ b/lib/OpenLayers/Handler/Keyboard.js @@ -3,12 +3,13 @@ * for the full text of the license. */ /** - * Handler for dragging a rectangle across the map. Keyboard is displayed - * on mouse down, moves on mouse move, and is finished on mouse up. - * - * @class * @requires OpenLayers/Handler.js * @requires OpenLayers/Events.js + * + * Class: OpenLayers.handler.Keyboard + * + * Inherits from: + * - */ OpenLayers.Handler.Keyboard = OpenLayers.Class.create(); OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, { @@ -18,14 +19,21 @@ OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Han /* supported named callbacks are: keyup, keydown, keypress */ - /** constant */ + /** + * Constant: KEY_EVENTS + * keydown, keypress, keyup + */ KEY_EVENTS: ["keydown", "keypress", "keyup"], - /** @type Function - * @private + /** + * Property: eventListener + * *Private*. {Function} */ eventListener: null, + /** + * Constructor: OpenLayers.Handler.Keyboard + */ initialize: function () { OpenLayers.Handler.prototype.initialize.apply(this, arguments); // cache the bound event listener method so it can be unobserved later @@ -33,7 +41,7 @@ OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Han }, /** - * + * Method: destroy */ destroy: function() { this.deactivate(); @@ -41,6 +49,9 @@ OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Han OpenLayers.Control.prototype.destroy.apply(this, arguments); }, + /** + * Method: activate + */ activate: function() { if (OpenLayers.Handler.prototype.activate.apply(this, arguments)) { for (var i = 0; i < this.KEY_EVENTS.length; i++) { @@ -53,6 +64,9 @@ OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Han } }, + /** + * Method: deactivate + */ deactivate: function() { if (OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { for (var i = 0; i < this.KEY_EVENTS.length; i++) { @@ -65,6 +79,9 @@ OpenLayers.Handler.Keyboard.prototype = OpenLayers.Class.inherit( OpenLayers.Han } }, + /** + * Method: handleKeyEvent + */ handleKeyEvent: function (evt) { if (this.checkModifiers(evt)) { this.callback(evt.type, [evt.charCode || evt.keyCode]); diff --git a/lib/OpenLayers/Handler/MouseWheel.js b/lib/OpenLayers/Handler/MouseWheel.js index 91477cabbb..2dedb8b90d 100644 --- a/lib/OpenLayers/Handler/MouseWheel.js +++ b/lib/OpenLayers/Handler/MouseWheel.js @@ -3,33 +3,40 @@ * for the full text of the license. */ /** + * @requires OpenLayers/Handler.js + * + * Class: OpenLayers.Handler.MouseWheel * Handler for wheel up/down events. * - * @class - * @requires OpenLayers/Handler.js + * Inherits from: + * - */ OpenLayers.Handler.MouseWheel = OpenLayers.Class.create(); OpenLayers.Handler.MouseWheel.prototype = OpenLayers.Class.inherit( OpenLayers.Handler, { - /** @type function **/ + /** + * Property: wheelListener + * {function} + */ wheelListener: null, - /** @type OpenLayers.Pixel - * @private - * - * mousePosition is necessary because evt.clientX/Y is buggy in Moz on - * wheel events, so we cache and use the value from the last mousemove. - **/ + /** + * Property: mousePosition + * *Private*. {} mousePosition is necessary because + * evt.clientX/Y is buggy in Moz on wheel events, so we cache and use the + * value from the last mousemove. + */ mousePosition: null, /** - * @constructor + * Constructor: OpenLayers.Handler.MouseWheel * - * @param {OpenLayers.Control} control - * @param {Object} callbacks An object containing a single function to be + * Parameters: + * control - {} + * callbacks - {Object} An object containing a single function to be * called when the drag operation is finished. * The callback should expect to recieve a single * argument, the point geometry. - * @param {Object} options + * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Handler.prototype.initialize.apply(this, arguments); @@ -37,7 +44,7 @@ OpenLayers.Handler.MouseWheel.prototype = OpenLayers.Class.inherit( OpenLayers.H }, /** - * + * Method: destroy */ destroy: function() { this.deactivate(); @@ -49,9 +56,12 @@ OpenLayers.Handler.MouseWheel.prototype = OpenLayers.Class.inherit( OpenLayers.H * Mouse ScrollWheel code thanks to http://adomas.org/javascript-mouse-wheel/ */ - /** Catch the wheel event and handle it xbrowserly + /** + * Method: onWheelEvent + * Catch the wheel event and handle it xbrowserly * - * @param {Event} e + * Parameters: + * e - {Event} */ onWheelEvent: function(e){ // first check keyboard modifiers @@ -98,10 +108,23 @@ OpenLayers.Handler.MouseWheel.prototype = OpenLayers.Class.inherit( OpenLayers.H } }, + /** + * Method: mousemove + * Update the stored mousePosition on every move. + * + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation + */ mousemove: function (evt) { this.mousePosition = evt.xy; }, + /** + * Method: activate + */ activate: function (evt) { if (OpenLayers.Handler.prototype.activate.apply(this, arguments)) { //register mousewheel events specifically on the window and document @@ -115,6 +138,9 @@ OpenLayers.Handler.MouseWheel.prototype = OpenLayers.Class.inherit( OpenLayers.H } }, + /** + * Method: deactivate + */ deactivate: function (evt) { if (OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { // unregister mousewheel events specifically on the window and document diff --git a/lib/OpenLayers/Handler/Path.js b/lib/OpenLayers/Handler/Path.js index 0b0c42a7b1..ad3a3fbeb6 100644 --- a/lib/OpenLayers/Handler/Path.js +++ b/lib/OpenLayers/Handler/Path.js @@ -4,66 +4,69 @@ /** - * Handler to draw a path on the map. Path is displayed on mouse down, - * moves on mouse move, and is finished on mouse up. - * - * @class * @requires OpenLayers/Handler/Point.js * @requires OpenLayers/Geometry/Point.js * @requires OpenLayers/Geometry/LineString.js + * + * Class: OpenLayers.Handler.Path + * Handler to draw a path on the map. Path is displayed on mouse down, + * moves on mouse move, and is finished on mouse up. + * + * Inherits from: + * - */ OpenLayers.Handler.Path = OpenLayers.Class.create(); OpenLayers.Handler.Path.prototype = OpenLayers.Class.inherit(OpenLayers.Handler.Point, { /** - * @type OpenLayers.Feature.Vector - * @private + * Property: line + * *Private*. {} */ line: null, /** - * In freehand mode, the handler starts the path on mouse down, adds a point - * for every mouse move, and finishes the path on mouse up. Outside of - * freehand mode, a point is added to the path on every mouse click and - * double-click finishes the path. - * - * @type Boolean + * Property: freehand + * {Boolean} In freehand mode, the handler starts the path on mouse down, + * adds a point for every mouse move, and finishes the path on mouse up. + * Outside of freehand mode, a point is added to the path on every mouse + * click and double-click finishes the path. */ freehand: false, /** - * If set, freehandToggle is checked on mouse events and will set the - * freehand mode to the opposite of this.freehand. To disallow toggling - * between freehand and non-freehand mode, set freehandToggle to null. - * Acceptable toggle values are 'shiftKey', 'ctrlKey', and 'altKey'. - * - * @type String + * Property: freehandToggle + * {String} If set, freehandToggle is checked on mouse events and will set + * the freehand mode to the opposite of this.freehand. To disallow + * toggling between freehand and non-freehand mode, set freehandToggle to + * null. Acceptable toggle values are 'shiftKey', 'ctrlKey', and 'altKey'. */ freehandToggle: 'shiftKey', /** - * @constructor + * Constructor: OpenLayers.Handler.Path + * Create a new path hander * - * @param {OpenLayers.Control} control - * @param {Array} callbacks An object with a 'done' property whos value is - * a function to be called when the path drawing is - * finished. The callback should expect to recieve a - * single argument, the line string geometry. - * If the callbacks object contains a 'point' - * property, this function will be sent each point - * as they are added. If the callbacks object contains - * a 'cancel' property, this function will be called when - * the handler is deactivated while drawing. The cancel - * should expect to receive a geometry. - * @param {Object} options + * Parameters: + * control - {} + * callbacks - {Array} An object with a 'done' property whos value is a + * function to be called when the path drawing is finished. The callback + * should expect to recieve a single argument, the line string geometry. + * If the callbacks object contains a 'point' property, this function will + * be sent each point as they are added. If the callbacks object contains + * a 'cancel' property, this function will be called when the handler is + * deactivated while drawing. The cancel should expect to receive a + * geometry. + * options - {Object} An optional object with properties to be set on the + * handler */ initialize: function(control, callbacks, options) { OpenLayers.Handler.Point.prototype.initialize.apply(this, arguments); }, /** - * Add temporary geometries + * Method: createFeature + * *Private*. Add temporary geometries */ createFeature: function() { this.line = new OpenLayers.Feature.Vector( @@ -73,7 +76,8 @@ OpenLayers.Handler.Path.prototype = }, /** - * Destroy temporary geometries + * Method: destroyFeature + * *Private*. Destroy temporary geometries */ destroyFeature: function() { this.line.destroy(); @@ -81,7 +85,8 @@ OpenLayers.Handler.Path.prototype = }, /** - * Add point to geometry. Send the point index to override + * Method: addPoint + * *Private*. Add point to geometry. Send the point index to override * the behavior of LinearRing that disregards adding duplicate points. */ addPoint: function() { @@ -91,9 +96,10 @@ OpenLayers.Handler.Path.prototype = }, /** - * Determine whether to behanve in freehand mode or not. + * Method: freehandMode + * *Private*. Determine whether to behave in freehand mode or not. * - * @type Boolean + * Return: {Boolean} */ freehandMode: function(evt) { return (this.freehandToggle && evt[this.freehandToggle]) ? @@ -101,8 +107,8 @@ OpenLayers.Handler.Path.prototype = }, /** - * Modify the existing geometry given the new point - * + * Method: modifyFeature + * *Private*. Modify the existing geometry given the new point */ modifyFeature: function() { var index = this.line.geometry.components.length - 1; @@ -111,7 +117,8 @@ OpenLayers.Handler.Path.prototype = }, /** - * Render geometries on the temporary layer. + * Method: drawFeature + * *Private*. Render geometries on the temporary layer. */ drawFeature: function() { this.layer.drawFeature(this.line, this.style); @@ -119,20 +126,25 @@ OpenLayers.Handler.Path.prototype = }, /** - * Return a clone of the relevant geometry. + * Method: geometryClone + * *Private*. Return a clone of the relevant geometry. * - * @type OpenLayers.Geometry.LineString + * Return: {} */ geometryClone: function() { return this.line.geometry.clone(); }, /** - * Handle mouse down. Add a new point to the geometry and render it. - * Return determines whether to propagate the event on the map. + * Method: mousedown + * *Private*. Handle mouse down. Add a new point to the geometry and + * render it. Return determines whether to propagate the event on the map. * - * @param {Event} evt - * @type Boolean + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ mousedown: function(evt) { // ignore double-clicks @@ -156,11 +168,15 @@ OpenLayers.Handler.Path.prototype = }, /** - * Handle mouse move. Adjust the geometry and redraw. + * Method: mousemove + * *Private*. Handle mouse move. Adjust the geometry and redraw. * Return determines whether to propagate the event on the map. * - * @param {Event} evt - * @type Boolean + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ mousemove: function (evt) { if(this.drawing) { @@ -178,11 +194,15 @@ OpenLayers.Handler.Path.prototype = }, /** - * Handle mouse up. Send the latest point in the geometry to the control. - * Return determines whether to propagate the event on the map. + * Method: mouseup + * *Private*. Handle mouse up. Send the latest point in the geometry to + * the control. Return determines whether to propagate the event on the map. * - * @param {Event} evt - * @type Boolean + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ mouseup: function (evt) { this.mouseDown = false; @@ -201,10 +221,15 @@ OpenLayers.Handler.Path.prototype = }, /** - * Handle double-clicks. Finish the geometry and send it back + * Method: dblclick + * *Private*. Handle double-clicks. Finish the geometry and send it back * to the control. * - * @param {Event} evt + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ dblclick: function(evt) { if(!this.freehandMode(evt)) { @@ -215,6 +240,9 @@ OpenLayers.Handler.Path.prototype = return false; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Handler.Path" }); diff --git a/lib/OpenLayers/Handler/Point.js b/lib/OpenLayers/Handler/Point.js index 435ce7025d..203cc3aadc 100644 --- a/lib/OpenLayers/Handler/Point.js +++ b/lib/OpenLayers/Handler/Point.js @@ -4,65 +4,73 @@ /** - * Handler to draw a point on the map. Point is displayed on mouse down, - * moves on mouse move, and is finished on mouse up. - * - * @class * @requires OpenLayers/Handler.js * @requires OpenLayers/Geometry/Point.js + * + * Class: OpenLayers.Handler.Point + * Handler to draw a point on the map. Point is displayed on mouse down, + * moves on mouse move, and is finished on mouse up. The handler triggers + * callbacks for 'done' and 'cancel'. Create a new instance with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Handler.Point = OpenLayers.Class.create(); OpenLayers.Handler.Point.prototype = OpenLayers.Class.inherit(OpenLayers.Handler, { /** - * @type OpenLayers.Feature.Vector - * @private + * Property: point + * {} The currently drawn point */ point: null, /** - * @type OpenLayers.Layer.Vector - * @private + * Property: layer + * {} The temporary drawing layer */ layer: null, /** - * @type Boolean - * @private + * Property: drawing + * {Boolean} A point is being drawn */ drawing: false, /** - * @type Boolean - * @private + * Property: mouseDown + * {Boolean} The mouse is down */ mouseDown: false, /** - * @type OpenLayers.Pixel - * @private + * Property: lastDown + * {} Location of the last mouse down */ lastDown: null, /** - * @type OpenLayers.Pixel - * @private + * Property: lastUp + * {} */ lastUp: null, /** - * @constructor + * Constructor: OpenLayers.Handler.Point + * Create a new point handler. * - * @param {OpenLayers.Control} control - * @param {Array} callbacks An object with a 'done' property whos value is - * a function to be called when the point drawing - * is finished. The callback should expect to - * recieve a single argument, the point geometry. - * If the callbacks object contains a 'cancel' property, - * this function will be called when the handler is deactivated - * while drawing. The cancel should expect to receive a geometry. - * @param {Object} options + * Parameters: + * control - {} The control that owns this handler + * callbacks - {Array} An object with a 'done' property whos value is a + * function to be called when the point drawing is finished. + * The callback should expect to recieve a single argument, + * the point geometry. If the callbacks object contains a + * 'cancel' property, this function will be called when the + * handler is deactivated while drawing. The cancel should + * expect to receive a geometry. + * options - {Object} An optional object with properties to be set on the + * handler */ initialize: function(control, callbacks, options) { // TBD: deal with style @@ -72,6 +80,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * APIMethod: activate * turn on the handler */ activate: function() { @@ -87,6 +96,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: createFeature * Add temporary features */ createFeature: function() { @@ -95,6 +105,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * APIMethod: deactivate * turn off the handler */ deactivate: function() { @@ -111,6 +122,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: destroyFeature * Destroy the temporary geometries */ destroyFeature: function() { @@ -118,6 +130,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: finalize * Finish the geometry and call the "done" callback. */ finalize: function() { @@ -131,6 +144,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * APIMethod: cancel * Finish the geometry and call the "cancel" callback. */ cancel: function() { @@ -144,7 +158,14 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: dblclick * Handle double clicks. + * + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ dblclick: function(evt) { OpenLayers.Event.stop(evt); @@ -152,6 +173,7 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: drawFeature * Render features on the temporary layer. */ drawFeature: function() { @@ -159,20 +181,25 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: geometryClone * Return a clone of the relevant geometry. * - * @type OpenLayers.Geometry.Point + * Return: {} */ geometryClone: function() { return this.point.geometry.clone(); }, /** - * Handle mouse down. Add a new point to the geometry and render it. + * Method: mousedown + * Handle mouse down. Adjust the geometry and redraw. * Return determines whether to propagate the event on the map. * - * @param {Event} evt - * @type Boolean + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ mousedown: function(evt) { // check keyboard modifiers @@ -196,13 +223,17 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: mousemove * Handle mouse move. Adjust the geometry and redraw. * Return determines whether to propagate the event on the map. * - * @param {Event} evt - * @type Boolean + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ - mousemove: function (evt) { + mousemove: function (evt) { if(this.drawing) { var lonlat = this.map.getLonLatFromPixel(evt.xy); this.point.geometry.x = lonlat.lon; @@ -213,13 +244,17 @@ OpenLayers.Handler.Point.prototype = }, /** + * Method: mouseup * Handle mouse up. Send the latest point in the geometry to the control. * Return determines whether to propagate the event on the map. - * - * @param {Event} evt - * @type Boolean + * + * Parameters: + * evt - {Event} The browser event + * + * Return: + * {Boolean} Allow event propagation */ - mouseup: function (evt) { + mouseup: function (evt) { if(this.drawing) { this.finalize(); return false; @@ -228,6 +263,9 @@ OpenLayers.Handler.Point.prototype = } }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Handler.Point" }); diff --git a/lib/OpenLayers/Handler/Polygon.js b/lib/OpenLayers/Handler/Polygon.js index 8225c5e038..9faa73d0a7 100644 --- a/lib/OpenLayers/Handler/Polygon.js +++ b/lib/OpenLayers/Handler/Polygon.js @@ -4,28 +4,34 @@ /** - * Handler to draw a path on the map. Polygon is displayed on mouse down, - * moves on mouse move, and is finished on mouse up. - * - * @class * @requires OpenLayers/Handler/Path.js * @requires OpenLayers/Geometry/Polygon.js + * + * Class: OpenLayers.Handler.Polygon + * Handler to draw a polygon on the map. Polygon is displayed on mouse down, + * moves on mouse move, and is finished on mouse up. + * + * Inherits from: + * - + * - */ OpenLayers.Handler.Polygon = OpenLayers.Class.create(); OpenLayers.Handler.Polygon.prototype = OpenLayers.Class.inherit(OpenLayers.Handler.Path, { /** - * @type OpenLayers.Feature.Vector - * @private + * Parameter: polygon + * *Private*. {} */ polygon: null, /** - * @constructor + * Constructor: OpenLayers.Handler.Polygon + * Create a Polygon Handler. * - * @param {OpenLayers.Control} control - * @param {Array} callbacks An object with a 'done' property whos value is + * Parameters: + * control - {} + * callbacks - {Array} An object with a 'done' property whos value is * a function to be called when the path drawing is * finished. The callback should expect to recieve a * single argument, the polygon geometry. @@ -35,13 +41,14 @@ OpenLayers.Handler.Polygon.prototype = * a 'cancel' property, this function will be called when * the handler is deactivated while drawing. The cancel * should expect to receive a geometry. - * @param {Object} options + * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Handler.Path.prototype.initialize.apply(this, arguments); }, /** + * Method: createFeature * Add temporary geometries */ createFeature: function() { @@ -55,6 +62,7 @@ OpenLayers.Handler.Polygon.prototype = }, /** + * Method: destroyFeature * Destroy temporary geometries */ destroyFeature: function() { @@ -63,6 +71,7 @@ OpenLayers.Handler.Polygon.prototype = }, /** + * Method: modifyFeature * Modify the existing geometry given the new point * */ @@ -73,6 +82,7 @@ OpenLayers.Handler.Polygon.prototype = }, /** + * Method: drawFeature * Render geometries on the temporary layer. */ drawFeature: function() { @@ -81,19 +91,23 @@ OpenLayers.Handler.Polygon.prototype = }, /** + * Method: geometryClone * Return a clone of the relevant geometry. * - * @type OpenLayers.Geometry.Polygon + * Return: + * {} */ geometryClone: function() { return this.polygon.geometry.clone(); }, /** + * Method: dblclick * Handle double-clicks. Finish the geometry and send it back * to the control. * - * @param {Event} evt + * Parameters: + * evt - {Event} */ dblclick: function(evt) { if(!this.freehandMode(evt)) { diff --git a/lib/OpenLayers/Icon.js b/lib/OpenLayers/Icon.js index 5d48781d2a..6301d86f4c 100644 --- a/lib/OpenLayers/Icon.js +++ b/lib/OpenLayers/Icon.js @@ -4,38 +4,54 @@ /** - * @class + * Class: OpenLayers.Icon */ OpenLayers.Icon = OpenLayers.Class.create(); OpenLayers.Icon.prototype = { - /** image url - * @type String */ - url: null, - - /** @type OpenLayers.Size */ - size:null, - - /** distance in pixels to offset the image when being rendered - * @type OpenLayers.Pixel */ - offset: null, - - /** Function to calculate the offset (based on the size) - * @type OpenLayers.Pixel */ - calculateOffset: null, - - /** @type DOMElement */ - imageDiv: null, - - /** @type OpenLayers.Pixel */ - px: null, + /** + * Property: url + * {String} image url + */ + url: null, /** - * @constructor + * Property: size + * {} + */ + size: null, + + /** + * Property: offset + * {} distance in pixels to offset the image when being rendered + */ + offset: null, + + /** + * Property: calculateOffset + * {} Function to calculate the offset (based on the size) + */ + calculateOffset: null, + + /** + * Property: imageDiv + * {DOMElement} + */ + imageDiv: null, + + /** + * Property: px + * {} + */ + px: null, + + /** + * Constructor: OpenLayers.Icon + * Creates an icon, which is an image tag in a div. * - * @param {String} url - * @param {OpenLayers.Size} size - * @param {Function} calculateOffset + * url - {String} + * size - {} + * calculateOffset - {Function} */ initialize: function(url, size, offset, calculateOffset) { this.url = url; @@ -47,6 +63,10 @@ OpenLayers.Icon.prototype = { this.imageDiv = OpenLayers.Util.createAlphaImageDiv(id); }, + /** + * Method: destroy + * nullify references to prevent circular references and memory leaks + */ destroy: function() { OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild); this.imageDiv.innerHTML = ""; @@ -54,8 +74,10 @@ OpenLayers.Icon.prototype = { }, /** - * @returns A fresh copy of the icon. - * @type OpenLayers.Icon + * Method: clone + * + * Returns: + * {} A fresh copy of the icon. */ clone: function() { return new OpenLayers.Icon(this.url, @@ -65,7 +87,9 @@ OpenLayers.Icon.prototype = { }, /** - * @param {OpenLayers.Size} size + * Method: setSize + * + * size - {} */ setSize: function(size) { if (size != null) { @@ -75,10 +99,14 @@ OpenLayers.Icon.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: draw + * Move the div to the given pixel. * - * @return A new DOM Image of this icon set at the location passed-in - * @type DOMElement + * Parameters: + * px - {} + * + * Returns: + * {DOMElement} A new DOM Image of this icon set at the location passed-in */ draw: function(px) { OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, @@ -92,8 +120,12 @@ OpenLayers.Icon.prototype = { }, - /** Change the icon's opacity - * @param {float} opacity + /** + * Method: setOpacity + * Change the icon's opacity + * + * Parameters: + * opacity - {float} */ setOpacity: function(opacity) { OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, null, null, @@ -102,7 +134,11 @@ OpenLayers.Icon.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: moveTo + * move icon to passed in px. + * + * Parameters: + * px - {} */ moveTo: function (px) { //if no px passed in, use stored location @@ -123,9 +159,12 @@ OpenLayers.Icon.prototype = { } }, - /** Hide or show the icon - * - * @param {Boolean} display + /** + * Method: display + * Hide or show the icon + * + * Parameters: + * display - {Boolean} */ display: function(display) { this.imageDiv.style.display = (display) ? "" : "none"; diff --git a/lib/OpenLayers/Layer.js b/lib/OpenLayers/Layer.js index d75b7704c7..15eaff2417 100644 --- a/lib/OpenLayers/Layer.js +++ b/lib/OpenLayers/Layer.js @@ -4,155 +4,211 @@ /** - * @class * @requires OpenLayers/Map.js + * + * Class: OpenLayers.Layer */ OpenLayers.Layer = OpenLayers.Class.create(); OpenLayers.Layer.prototype = { - /** @type String */ + /** + * APIProperty: id + * {String} + */ id: null, - /** @type String */ + /** + * APIProperty: name + * {String} + */ name: null, - /** @type DOMElement */ + /** + * APIProperty: div + * {DOMElement} + */ div: null, - /** supported application event types - * - * @type Array */ - EVENT_TYPES: [ - "loadstart", "loadend", "loadcancel"], - - /** @type OpenLayers.Events */ + /** + * Constant: EVENT_TYPES + * {Array(String)} Supported application event types + */ + EVENT_TYPES: [ "loadstart", "loadend", "loadcancel"], + + /** + * APIProperty: events`` + * {} + */ events: null, - /** This variable is set when the layer is added to the map, via the - * accessor function setMap() - * - * @type OpenLayers.Map */ + /** + * APIProperty: map + * {} This variable is set when the layer is added to + * the map, via the accessor function setMap(). + */ map: null, - /** Whether or not the layer is a base layer. This should be set - * individually by all subclasses. - * Default is false - * - * @type Boolean + /** + * APIProperty: isBaseLayer + * {Boolean} Whether or not the layer is a base layer. This should be set + * individually by all subclasses. + * Default is false */ isBaseLayer: false, - /** asserts whether or not the layer's images have an alpha channel - * - * @type boolean */ + /** + * Property: alpha + * {Boolean} Whether or not the layer's images have an alpha channel + */ alpha: false, - /** should the layer's name appear in the layer switcher? - * - * @type boolean */ + /** + * APIProperty: displayInLayerSwitcher + * {Boolean} Should the layer's name appear in the layer switcher? + */ displayInLayerSwitcher: true, - /** Whether or not the layer should be displayed in the map - * - * @type Boolean + /** + * APIProperty: visibility + * {Boolean} Whether or not the layer should be displayed in the map */ visibility: true, - /** Whether or not the map's current resolution is within this layer's - * min/max range -- this is set in map's setCenter() whenever zoom - * changes - * - * @type Boolean + /** + * APIProperty: inRange + * {Boolean} Whether or not the map's current resolution is within this + * layer's min/max range -- this is set in map's setCenter() + * whenever zoom changes. */ inRange: false, /** - * For layers that use Tile.Image, the image size is cached here. For - * layers without a gutter, the image size is equal to the tile size. - * For layers with a gutter, the image is larger than the tile by twice - * the gutter in each dimension. - * - * @type OpenLayers.Size - * @private + * Propery: imageSize + * {} For layers with a gutter, the image is larger than + * the tile by twice the gutter in each dimension. */ imageSize: null, /** - * For layers that use Tile.Image, the image offset is cached here. - * Layers without a gutter have zero offset. For layers with a gutter, - * the image offset represents displacement due to the gutter. - * - * @type OpenLayers.Pixel - * @private + * Property: imageOffset + * {} For layers with a gutter, the image offset + * represents displacement due to the gutter. */ imageOffset: null, // OPTIONS - /** @type Array */ + /** + * Property: options + * {Object} + */ options: null, - /** Determines the width (in pixels) of the gutter around image tiles - * to ignore. By setting this property to a non-zero value, images - * will be requested that are wider and taller than the tile size by - * a value of 2 x gutter. This allows artifacts of rendering at tile - * edges to be ignored. Set a gutter value that is equal to half the size - * of the widest symbol that needs to be displayed. Defaults to zero. - * Non-tiled layers always have zero gutter. - * - * @type Int - */ + /** + * Property: gutter + * {Integer} Determines the width (in pixels) of the gutter around image + * tiles to ignore. By setting this property to a non-zero + * value, images will be requested that are wider and taller + * than the tile size by a value of 2 x gutter. This allows + * artifacts of rendering at tile edges to be ignored. Set a + * gutter value that is equal to half the size of the widest + * symbol that needs to be displayed. Defaults to zero. + * Non-tiled layers always have zero gutter. + */ gutter: 0, - /** @type String */ + /** + * Property: projection + * {String} Set in the layer options to override the default projection + * string this layer - also set maxExtent, maxResolution, and + * units if appropriate. + */ projection: null, - /** @type String */ + /** + * Property: units + * {String} The layer map units. Defaults to 'degrees'. Possible values + * are 'degrees' (or 'dd'), 'm', 'ft', 'km', 'mi', 'inches'. + */ units: null, - /** @type Array */ + /** + * Property: scales + * {Array} + */ scales: null, - /** @type Array */ + /** + * Property: resolutions + * {Array} + */ resolutions: null, - /** @type OpenLayers.Bounds */ + /** + * Property: maxExtent + * {} + */ maxExtent: null, - /** @type OpenLayers.Bounds */ + /** + * Property: minExtent + * {} + */ minExtent: null, - /** @type float */ + /** + * Property: maxResolution + * {Float} Default max is 360 deg / 256 px, which corresponds to + * zoom level 0 on gmaps. Specify a different value in the layer + * options if you are not using a geographic projection and + * displaying the whole world. + */ maxResolution: null, - /** @type float */ + /** + * Property: minResolution + * {Float} + */ minResolution: null, - /** @type int */ + /** + * Property: numZoomLevels + * {Integer} + */ numZoomLevels: null, - /** @type float */ + /** + * Property: minScale + * {Float} + */ minScale: null, - /** @type float */ + /** + * Property: maxScale + * {Float} + */ maxScale: null, - /** @type Boolean */ + /** + * Property: displayOutsideMaxExtent + * {Boolean} Request map tiles that are completely outside of the max extent + * for this layer. Defaults to false + */ displayOutsideMaxExtent: false, - /** - * wrapDateLine -- #487 for more info. - * - * @type Boolean + /** + * Property: wrapDateLine + * {Boolean} #487 for more info. */ wrapDateLine: false, /** - * @constructor - * - * @param {String} name - * @param {Object} options Hashtable of extra options to tag onto the layer + * Constructor: OpenLayers.Layer + * + * Parameters: + * name - {String} The layer name + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, options) { @@ -179,12 +235,14 @@ OpenLayers.Layer.prototype = { }, /** + * Method: destroy * Destroy is a destructor: this is to alleviate cyclic references which - * the Javascript garbage cleaner can not take care of on its own. - * - * @param {Boolean} setNewBaseLayer Should a new baselayer be selected when - * this has been removed? - * Default is true + * the Javascript garbage cleaner can not take care of on its own. + * + * Parameters: + * setNewBaseLayer - {Boolean} Should a new baselayer be selected when + * this has been removed? + * Default is true. */ destroy: function(setNewBaseLayer) { if (setNewBaseLayer == null) { @@ -205,8 +263,13 @@ OpenLayers.Layer.prototype = { }, /** - * @returns An exact clone of this OpenLayers.Layer - * @type OpenLayers.Layer + * Method: clone + * + * Parameters: + * obj - {} The layer to be cloned + * + * Return: + * {} An exact clone of this */ clone: function (obj) { @@ -225,7 +288,10 @@ OpenLayers.Layer.prototype = { }, /** - * @param {String} newName + * APIMethod: setName + * + * Parameters: + * newName - {String} */ setName: function(newName) { if (newName != this.name) { @@ -237,7 +303,10 @@ OpenLayers.Layer.prototype = { }, /** - * @param {Object} newOptions + * APIMethod: addOptions + * + * Parameters: + * newOptions - {Object} */ addOptions: function (newOptions) { @@ -253,17 +322,21 @@ OpenLayers.Layer.prototype = { }, /** - * + * APIMethod: onMapResize + * This function can be implemented by subclasses */ onMapResize: function() { //this function can be implemented by subclasses }, /** - * @param {OpenLayers.Bounds} bound - * @param {Boolean} zoomChanged tells when zoom has changed, as layers - * have to do some init work in that case. - * @param {Boolean} dragging + * Method: moveTo + * + * Parameters: + * bound - {} + * zoomChanged - {Boolean} Tells when zoom has changed, as layers + * have to do some init work in that case. + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { var display = this.visibility; @@ -273,14 +346,17 @@ OpenLayers.Layer.prototype = { this.display(display); }, - /** Set the map property for the layer. This is done through an accessor - * so that subclasses can override this and take special action once - * they have their map variable set. + /** + * Method: setMap + * Set the map property for the layer. This is done through an accessor + * so that subclasses can override this and take special action once + * they have their map variable set. * - * Here we take care to bring over any of the necessary default properties - * from the map. + * Here we take care to bring over any of the necessary default properties + * from the map. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { if (this.map == null) { @@ -307,10 +383,12 @@ OpenLayers.Layer.prototype = { }, /** + * APIMethod: setTileSize * Set the tile size based on the map size. This also sets layer.imageSize - * and layer.imageOffset for use by Tile.Image. - * - * @param {OpenLayers.Size} + * and layer.imageOffset for use by Tile.Image. + * + * Parameters: + * size - {} */ setTileSize: function(size) { var tileSize = (size) ? size : @@ -336,25 +414,30 @@ OpenLayers.Layer.prototype = { }, /** - * @returns Whether or not the layer should be displayed (if in range) - * @type Boolean - */ + * APIMethod: getVisibility + * + * Return: + * {Boolean} Whether or not the layer should be displayed (if in range) + */ getVisibility: function() { return this.visibility; }, - /** Set the visibility flag for the layer and hide/show&redraw accordingly. - * Fire event unless otherwise specified + /** + * APIMethod: setVisibility + * Set the visibility flag for the layer and hide/show&redraw accordingly. + * Fire event unless otherwise specified * - * Note that visibility is no longer simply whether or not the layer's - * style.display is set to "block". Now we store a 'visibility' state - * property on the layer class, this allows us to remember whether or not - * we *desire* for a layer to be visible. In the case where the map's - * resolution is out of the layer's range, this desire may be subverted. - * - * @param {Boolean} visible Whether or not to display the layer - * (if in range) - * @param {Boolean} noEvent + * Note that visibility is no longer simply whether or not the layer's + * style.display is set to "block". Now we store a 'visibility' state + * property on the layer class, this allows us to remember whether or + * not we *desire* for a layer to be visible. In the case where the + * map's resolution is out of the layer's range, this desire may be + * subverted. + * + * Parameters: + * visible - {Boolean} Whether or not to display the layer (if in range) + * noEvent - {Boolean} */ setVisibility: function(visibility, noEvent) { if (visibility != this.visibility) { @@ -373,9 +456,12 @@ OpenLayers.Layer.prototype = { } }, - /** Hide or show the Layer + /** + * APIMethod: display + * Hide or show the Layer * - * @param {Boolean} display + * Parameters: + * display - {Boolean} */ display: function(display) { if (display != (this.div.style.display != "none")) { @@ -384,9 +470,11 @@ OpenLayers.Layer.prototype = { }, /** - * @returns Whether or not the layer is displayable at the current map's - * current resolution - * @type Boolean + * Method: calculateInRange + * + * Return: + * {Boolean} Whether or not the layer is displayable at the current map's + * current resolution */ calculateInRange: function() { var inRange = false; @@ -399,7 +487,10 @@ OpenLayers.Layer.prototype = { }, /** - * @param {Boolean} isBaseLayer + * APIMethod: setIsBaseLayer + * + * Parameters: + * isBaseLayer - {Boolean} */ setIsBaseLayer: function(isBaseLayer) { if (isBaseLayer != this.isBaseLayer) { @@ -416,19 +507,19 @@ OpenLayers.Layer.prototype = { /* */ /********************************************************/ - /** This method's responsibility is to set up the 'resolutions' array - * for the layer -- this array is what the layer will use to interface - * between the zoom levels of the map and the resolution display of the - * layer. + /** + * Method: initResolutions + * This method's responsibility is to set up the 'resolutions' array + * for the layer -- this array is what the layer will use to interface + * between the zoom levels of the map and the resolution display + * of the layer. * - * The user has several options that determine how the array is set up. + * The user has several options that determine how the array is set up. * - * For a detailed explanation, see the following wiki from the - * openlayers.org homepage: + * For a detailed explanation, see the following wiki from the + * openlayers.org homepage: * - * http://trac.openlayers.org/wiki/SettingZoomLevels - * - * @private + * http://trac.openlayers.org/wiki/SettingZoomLevels */ initResolutions: function() { @@ -550,9 +641,11 @@ OpenLayers.Layer.prototype = { }, /** - * @returns The currently selected resolution of the map, taken from the - * resolutions array, indexed by current zoom level. - * @type float + * APIMethod: getResolution + * + * Return: + * {Float} The currently selected resolution of the map, taken from the + * resolutions array, indexed by current zoom level. */ getResolution: function() { var zoom = this.map.getZoom(); @@ -560,9 +653,11 @@ OpenLayers.Layer.prototype = { }, /** - * @returns A Bounds object which represents the lon/lat bounds of the - * current viewPort. - * @type OpenLayers.Bounds + * APIMethod: getExtent + * + * Return: + * {} A Bounds object which represents the lon/lat + * bounds of the current viewPort. */ getExtent: function() { // just use stock map calculateBounds function -- passing no arguments @@ -572,14 +667,17 @@ OpenLayers.Layer.prototype = { }, /** - * @param {OpenLayers.Bounds} bounds + * APIMethod: getZoomForExtent + * + * Parameters: + * bounds - {} * - * @returns The index of the zoomLevel (entry in the resolutions array) + * Return: + * {Integer} The index of the zoomLevel (entry in the resolutions array) * that still contains the passed-in extent. We do this by * calculating the ideal resolution for the given exteng (based * on the map size) and then find the smallest resolution that * is greater than this ideal resolution. - * @type int */ getZoomForExtent: function(extent) { var viewSize = this.map.getSize(); @@ -590,12 +688,15 @@ OpenLayers.Layer.prototype = { }, /** - * @param {float} resolution - * - * @returns The index of the zoomLevel (entry in the resolutions array) + * APIMethod: getZoomForResolution + * + * Parameters: + * resolution - {Float} + * + * Return: + * {Integer} The index of the zoomLevel (entry in the resolutions array) * that is the smallest resolution that is greater than the * passed-in resolution. - * @type int */ getZoomForResolution: function(resolution) { @@ -608,11 +709,15 @@ OpenLayers.Layer.prototype = { }, /** - * @param {OpenLayers.Pixel} viewPortPx + * APIMethod: getLonLatFromViewPortPx + * + * Parameters: + * viewPortPx - {} * - * @returns An OpenLayers.LonLat which is the passed-in view port - * OpenLayers.Pixel, translated into lon/lat by the layer - * @type OpenLayers.LonLat + * Return: + * {} An OpenLayers.LonLat which is the passed-in + * view port , translated into + * lon/lat by the layer */ getLonLatFromViewPortPx: function (viewPortPx) { var lonlat = null; @@ -637,11 +742,15 @@ OpenLayers.Layer.prototype = { }, /** - * @param {OpenLayers.LonLat} lonlat + * APIMethod: getViewPortPxFromLonLat + * + * Parameters: + * lonlat - {} * - * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, - * translated into view port pixels - * @type OpenLayers.Pixel + * Return: + * {} An which is the passed-in + * ,translated into view + * port pixels. */ getViewPortPxFromLonLat: function (lonlat) { var px = null; @@ -657,8 +766,11 @@ OpenLayers.Layer.prototype = { }, /** + * APIMethod: setOpacity * Sets the opacity for the entire layer (all images) - * @param {Float} opacity + * + * Parameter: + * opacity - {Float} */ setOpacity: function(opacity) { if (opacity != this.opacity) { @@ -672,22 +784,26 @@ OpenLayers.Layer.prototype = { }, /** - * @param {int} zIdx - * @private - */ - setZIndex: function (zIdx) { - this.div.style.zIndex = zIdx; + * Method: setZIndex + * + * Parameters: + * zIndex - {Integer} + */ + setZIndex: function (zIndex) { + this.div.style.zIndex = zIndex; }, /** - * This function will take a bounds, and if wrapDateLine option is set - * on the layer, it will return a bounds which is wrapped around the world. - * We do not wrap for bounds which *cross* the maxExtent.left/right, only - * bounds which are entirely to the left or entirely to the right. - * - * @param {OpenLayers.Bounds} bounds - * @private - */ + * Method: adjustBounds + * This function will take a bounds, and if wrapDateLine option is set + * on the layer, it will return a bounds which is wrapped around the + * world. We do not wrap for bounds which *cross* the + * maxExtent.left/right, only bounds which are entirely to the left + * or entirely to the right. + * + * Parameters: + * bounds - {} + */ adjustBounds: function (bounds) { if (this.gutter) { diff --git a/lib/OpenLayers/Layer/Boxes.js b/lib/OpenLayers/Layer/Boxes.js index a50610de35..4f55f83c18 100644 --- a/lib/OpenLayers/Layer/Boxes.js +++ b/lib/OpenLayers/Layer/Boxes.js @@ -4,31 +4,37 @@ /** - * @class - * * @requires OpenLayers/Layer.js * @requires OpenLayers/Layer/Markers.js + * + * Class: OpenLayers.Layer.Boxes + * Draw divs as 'boes' on the layer. + * + * Inherits from: + * - */ OpenLayers.Layer.Boxes = OpenLayers.Class.create(); OpenLayers.Layer.Boxes.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Markers, { /** - * @constructor + * Constructor: OpenLayers.Layer.Boxes * - * @param {String} name - * @param {Object} options Hashtable of extra options to tag onto the layer + * Parameters: + * name - {String} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function (name, options) { OpenLayers.Layer.Markers.prototype.initialize.apply(this, arguments); }, - /** Calculate the pixel location for the marker, create it, and + /** + * Method: drawMarker + * Calculate the pixel location for the marker, create it, and * add it to the layer's div * - * @private - * - * @param {OpenLayers.Marker.Box} marker + * Parameters: + * marker - {} */ drawMarker: function(marker) { var bounds = marker.bounds; @@ -51,9 +57,11 @@ OpenLayers.Layer.Boxes.prototype = }, - /** OVERRIDDEN + /** + * APIMethod: removeMarker * - * @param {OpenLayers.Marker} marker + * Parameters: + * marker - {} */ removeMarker: function(marker) { OpenLayers.Util.removeItem(this.markers, marker); diff --git a/lib/OpenLayers/Layer/EventPane.js b/lib/OpenLayers/Layer/EventPane.js index 89f248a26d..4a408f5a7e 100644 --- a/lib/OpenLayers/Layer/EventPane.js +++ b/lib/OpenLayers/Layer/EventPane.js @@ -4,42 +4,55 @@ /** - * @class - * * @requires OpenLayers/Layer.js * @requires OpenLayers/Util.js + * + * Class: OpenLayers.Layer.EventPane + * Base class for 3rd party layers. Create a new event pane layer with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Layer.EventPane = OpenLayers.Class.create(); OpenLayers.Layer.EventPane.prototype = OpenLayers.Class.inherit( OpenLayers.Layer, { - /** EventPaned layers are always base layers, by necessity. - * - * @type Boolean */ + /** + * Property: isBaseLayer + * {Boolean} EventPaned layers are always base layers, by necessity. + */ isBaseLayer: true, - /** EventPaned layers are fixed by default. - * - * @type Boolean */ + /** + * APIProperty: isFixed + * {Boolean} EventPaned layers are fixed by default. + */ isFixed: true, - /** @type DOMElement */ + /** + * Property: pane + * {DOMElement} A reference to the element that controls the events. + */ pane: null, - /** This is the object which will be used to load the 3rd party library - * in the case of the google layer, this will be of type GMap, - * in the case of the ve layer, this will be of type VEMap - * - * @type Object */ + /** + * Property: mapObject + * {Object} This is the object which will be used to load the 3rd party library + * in the case of the google layer, this will be of type GMap, + * in the case of the ve layer, this will be of type VEMap + */ mapObject: null, /** - * @constructor - * - * @param {String} name - * @param {Object} options Hashtable of extra options to tag onto the layer + * Constructor: OpenLayers.Layer.EventPane + * Create a new event pane layer + * + * Parameters: + * name - {String} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, options) { OpenLayers.Layer.prototype.initialize.apply(this, arguments); @@ -49,7 +62,8 @@ OpenLayers.Layer.EventPane.prototype = }, /** - * + * APIMethod: destroy + * Deconstruct this layer. */ destroy: function() { this.mapObject = null; @@ -57,11 +71,14 @@ OpenLayers.Layer.EventPane.prototype = }, - /** Set the map property for the layer. This is done through an accessor - * so that subclasses can override this and take special action once - * they have their map variable set. - * - * @param {OpenLayers.Map} map + /** + * Method: setMap + * Set the map property for the layer. This is done through an accessor + * so that subclasses can override this and take special action once + * they have their map variable set. + * + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.prototype.setMap.apply(this, arguments); @@ -90,11 +107,10 @@ OpenLayers.Layer.EventPane.prototype = } }, - /** If we can't load the GMap, then display an error message to the - * user and tell them where to go for help. - * - * @private - * + /** + * Method: loadWarningMessage + * If we can't load the map lib, then display an error message to the + * user and tell them where to go for help. */ loadWarningMessage:function() { @@ -126,8 +142,12 @@ OpenLayers.Layer.EventPane.prototype = }, - /** - * @param {Boolean} display + /** + * Method: display + * Set the display on the pane + * + * Parameters: + * display - {Boolean} */ display: function(display) { OpenLayers.Layer.prototype.display.apply(this, arguments); @@ -135,17 +155,25 @@ OpenLayers.Layer.EventPane.prototype = }, /** - * @param {int} zIndex + * Method: setZIndex + * Set the z-index order for the pane. + * + * Parameters: + * zIndex - {int} */ setZIndex: function (zIndex) { OpenLayers.Layer.prototype.setZIndex.apply(this, arguments); this.pane.style.zIndex = parseInt(this.div.style.zIndex) + 1; }, - /** - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + /** + * Method: moveTo + * Handle calls to move the layer. + * + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { OpenLayers.Layer.prototype.moveTo.apply(this, arguments); @@ -182,12 +210,16 @@ OpenLayers.Layer.EventPane.prototype = /********************************************************/ /** - * @param {OpenLayers.Pixel} viewPortPx + * Method: getLonLatFromViewPortPx + * Get a map location from a pixel location + * + * Parameters: + * viewPortPx - {} * - * @returns An OpenLayers.LonLat which is the passed-in view port - * OpenLayers.Pixel, translated into lon/lat by GMAPS - * If gmap is not loaded or not centered, returns null - * @type OpenLayers.LonLat + * Return: + * {} An OpenLayers.LonLat which is the passed-in view + * port OpenLayers.Pixel, translated into lon/lat by map lib + * If the map lib is not loaded or not centered, returns null */ getLonLatFromViewPortPx: function (viewPortPx) { var lonlat = null; @@ -202,12 +234,16 @@ OpenLayers.Layer.EventPane.prototype = /** - * @param {OpenLayers.LonLat} lonlat + * Method: getViewPortPxFromLonLat + * Get a pixel location from a map location * - * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, - * translated into view port pixels BY GMAPS - * If gmap is not loaded or not centered, returns null - * @type OpenLayers.Pixel + * Parameters: + * lonlat - {} + * + * Return: + * {} An OpenLayers.Pixel which is the passed-in + * OpenLayers.LonLat, translated into view port pixels by map lib + * If map lib is not loaded or not centered, returns null */ getViewPortPxFromLonLat: function (lonlat) { var viewPortPx = null; @@ -236,12 +272,16 @@ OpenLayers.Layer.EventPane.prototype = // /** - * @param {Object} moLonLat + * Method: getOLLonLatFromMapObjectLonLat + * Get an OL style map location from a 3rd party style map location + * + * Parameters + * moLonLat - {Object} * - * @returns An OpenLayers.LonLat, translated from the passed in + * Return: + * {} An OpenLayers.LonLat, translated from the passed in * MapObject LonLat * Returns null if null value is passed in - * @type OpenLayers.LonLat */ getOLLonLatFromMapObjectLonLat: function(moLonLat) { var olLonLat = null; @@ -254,12 +294,16 @@ OpenLayers.Layer.EventPane.prototype = }, /** - * @param {OpenLayers.LonLat} olLonLat + * Method: getMapObjectLonLatFromOLLonLat + * Get a 3rd party map location from an OL map location. + * + * Parameters: + * olLonLat - {} * - * @returns A MapObject LonLat, translated from the passed in + * Return: + * {Object} A MapObject LonLat, translated from the passed in * OpenLayers.LonLat * Returns null if null value is passed in - * @type Object */ getMapObjectLonLatFromOLLonLat: function(olLonLat) { var moLatLng = null; @@ -276,12 +320,16 @@ OpenLayers.Layer.EventPane.prototype = // /** - * @param {Object} moPixel + * Method: getOLPixelFromMapObjectPixel + * Get an OL pixel location from a 3rd party pixel location. + * + * Parameters: + * moPixel - {Object} * - * @returns An OpenLayers.Pixel, translated from the passed in + * Return: + * {} An OpenLayers.Pixel, translated from the passed in * MapObject Pixel * Returns null if null value is passed in - * @type OpenLayers.Pixel */ getOLPixelFromMapObjectPixel: function(moPixel) { var olPixel = null; @@ -294,12 +342,16 @@ OpenLayers.Layer.EventPane.prototype = }, /** - * @param {OpenLayers.Pixel} olPixel + * Method: getMapObjectPixelFromOLPixel + * Get a 3rd party pixel location from an OL pixel location + * + * Parameters: + * olPixel - {} * - * @returns A MapObject Pixel, translated from the passed in + * Return: + * {Object} A MapObject Pixel, translated from the passed in * OpenLayers.Pixel * Returns null if null value is passed in - * @type Object */ getMapObjectPixelFromOLPixel: function(olPixel) { var moPixel = null; @@ -309,6 +361,9 @@ OpenLayers.Layer.EventPane.prototype = return moPixel; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of this class + */ CLASS_NAME: "OpenLayers.Layer.EventPane" }); diff --git a/lib/OpenLayers/Layer/FixedZoomLevels.js b/lib/OpenLayers/Layer/FixedZoomLevels.js index 205ef42067..245e146ef3 100644 --- a/lib/OpenLayers/Layer/FixedZoomLevels.js +++ b/lib/OpenLayers/Layer/FixedZoomLevels.js @@ -2,10 +2,10 @@ * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ - - - -/** +/** + * @requires OpenLayers/Layer.js + * + * Class: OpenLayers.Layer.FixedZoomLevels * Some Layers will already have established zoom levels (like google * or ve). Instead of trying to determine them and populate a resolutions[] * Array with those values, we will hijack the resolution functionality @@ -37,15 +37,13 @@ * Whenever you implement a layer using OpenLayers.Layer.FixedZoomLevels, * it is your responsibility to provide the following three functions: * - * - getLonLatFromViewPortPx() - * - getViewPortPxFromLonLat() - * - getZoomForExtent() + * - getLonLatFromViewPortPx + * - getViewPortPxFromLonLat + * - getZoomForExtent * * ...those three functions should generally be provided by any reasonable * API that you might be working from. - * - * @requires OpenLayers/Layer.js - * @class + * */ OpenLayers.Layer.FixedZoomLevels = OpenLayers.Class.create(); OpenLayers.Layer.FixedZoomLevels.prototype = { @@ -60,7 +58,8 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { /********************************************************/ /** - * @constructor + * Constructor: OpenLayers.Layer.FixedZoomLevels + * Create a new fixed zoom levels layer. */ initialize: function() { //this class is only just to add the following functions... @@ -71,7 +70,8 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { }, /** - * + * Method: initResolutions + * Populate the resolutions array */ initResolutions: function() { @@ -112,9 +112,12 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { } }, - /** - * @returns Degrees per Pixel - * @type float + /** + * APIMethod: getResolution + * Get the current map resolution + * + * Return: + * {Float} Map units per Pixel */ getResolution: function() { @@ -134,12 +137,14 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { } }, - /** Calculates using px-> lonlat translation functions on tl and br - * corners of viewport + /** + * APIMethod: getExtent + * Calculates using px-> lonlat translation functions on tl and br + * corners of viewport * - * @returns A Bounds object which represents the lon/lat bounds of the - * current viewPort. - * @type OpenLayers.Bounds + * Return: + * {} A Bounds object which represents the lon/lat + * bounds of the current viewPort. */ getExtent: function () { var extent = null; @@ -164,11 +169,15 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { }, /** - * @param {float} resolution + * Method: getZoomForResolution + * Get the zoom level for a given resolution * - * @returns A suitable zoom level for the specified resolution. - * If no baselayer is set, returns null. - * @type int + * Parameters: + * resolution - {Float} + * + * Return: + * {Integer} A suitable zoom level for the specified resolution. + * If no baselayer is set, returns null. */ getZoomForResolution: function(resolution) { @@ -185,26 +194,30 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { - /********************************************************/ - /* */ - /* Translation Functions */ - /* */ - /* The following functions translate GMaps and OL */ - /* formats for Pixel, LonLat, Bounds, and Zoom */ - /* */ - /********************************************************/ - - - // - // TRANSLATION: MapObject Zoom <-> OpenLayers Zoom - // + /********************************************************/ + /* */ + /* Translation Functions */ + /* */ + /* The following functions translate GMaps and OL */ + /* formats for Pixel, LonLat, Bounds, and Zoom */ + /* */ + /********************************************************/ + + + // + // TRANSLATION: MapObject Zoom <-> OpenLayers Zoom + // /** - * @param {int} gZoom + * Method: getOLZoomFromMapObjectZoom + * Get the OL zoom index from the map object zoom level + * + * Parameters: + * moZoom - {Integer} * - * @returns An OpenLayers Zoom level, translated from the passed in gZoom - * Returns null if null value is passed in - * @type int + * Return: + * {Integer} An OpenLayers Zoom level, translated from the passed in zoom + * Returns null if null value is passed in */ getOLZoomFromMapObjectZoom: function(moZoom) { var zoom = null; @@ -215,11 +228,15 @@ OpenLayers.Layer.FixedZoomLevels.prototype = { }, /** - * @param {int} olZoom + * Method: getMapObjectZoomFromOLZoom + * Get the map object zoom level from the OL zoom level + * + * Parameters: + * olZoom - {Integer} * - * @returns A MapObject level, translated from the passed in olZoom - * Returns null if null value is passed in - * @type int + * Return: + * {Integer} A MapObject level, translated from the passed in olZoom + * Returns null if null value is passed in */ getMapObjectZoomFromOLZoom: function(olZoom) { var zoom = null; diff --git a/lib/OpenLayers/Layer/GML.js b/lib/OpenLayers/Layer/GML.js index f4ed95c1df..78314ace44 100644 --- a/lib/OpenLayers/Layer/GML.js +++ b/lib/OpenLayers/Layer/GML.js @@ -3,32 +3,41 @@ * for the full text of the license. */ /** - * Create a vector layer by parsing a GML file. The GML file is - * passed in as a parameter. - * @class - * * @requires OpenLayers/Layer/Vector.js * @requires OpenLayers/Ajax.js + + * Class: OpenLayers.Layer.GML + * Create a vector layer by parsing a GML file. The GML file is + * passed in as a parameter. + * + * Inherits from: + * - */ OpenLayers.Layer.GML = OpenLayers.Class.create(); OpenLayers.Layer.GML.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Vector, { /** - * Flag for whether the GML data has been loaded yet. - * @type Boolean + * Property: loaded + * {Boolean} Flag for whether the GML data has been loaded yet. */ loaded: false, + /** + * APIProperty: format + * {} The format you want the data to be parsed with. + */ format: null, /** - * @constructor - * - * @param {String} name - * @param {String} url URL of a GML file. - * @param {Object} options Hashtable of extra options to tag onto the layer. - * Options renderer {Object}: Typically SvgRenderer or VmlRenderer. + * Constructor: OpenLayers.Layer.GML + * Load and parse a single file on the web, according to the format + * provided via the 'format' option, defaulting to GML. + * + * Parameters: + * name - {String} + * url - {String} URL of a GML file. + * options - {Object} Hashtable of extra options to tag onto the layer. */ initialize: function(name, url, options) { var newArguments = new Array() @@ -38,14 +47,16 @@ OpenLayers.Layer.GML.prototype = }, /** + * APIMethod: setVisibility * Set the visibility flag for the layer and hide/show&redraw accordingly. * Fire event unless otherwise specified * GML will be loaded if the layer is being made visible for the first * time. * - * @param {Boolean} visible Whether or not to display the layer + * Parameters: + * visible - {Boolean} Whether or not to display the layer * (if in range) - * @param {Boolean} noEvent + * noEvent - {Boolean} */ setVisibility: function(visibility, noEvent) { OpenLayers.Layer.Vector.prototype.setVisibility.apply(this, arguments); @@ -56,11 +67,14 @@ OpenLayers.Layer.GML.prototype = }, /** + * Method: moveTo * If layer is visible and GML has not been loaded, load GML, then load GML * and call OpenLayers.Layer.Vector.moveTo() to redraw at the new location. - * @param {Object} bounds - * @param {Object} zoomChanged - * @param {Object} minor + * + * Parameters: + * bounds - {Object} + * zoomChanged - {Object} + * minor - {Object} */ moveTo:function(bounds, zoomChanged, minor) { OpenLayers.Layer.Vector.prototype.moveTo.apply(this, arguments); @@ -73,6 +87,9 @@ OpenLayers.Layer.GML.prototype = } }, + /** + * Method: loadGML + */ loadGML: function() { if (!this.loaded) { var results = OpenLayers.loadURL(this.url, null, this, this.requestSuccess, this.requestFailure); @@ -82,10 +99,12 @@ OpenLayers.Layer.GML.prototype = /** + * Method: requestSuccess * Process GML after it has been loaded. * Called by initialise() and loadUrl() after the GML has been loaded. - * @private - * @param {String} request + * + * Parameters: + * request - {String} */ requestSuccess:function(request) { var doc = request.responseXML; @@ -99,10 +118,12 @@ OpenLayers.Layer.GML.prototype = }, /** + * Method: requestFailure * Process a failed loading of GML. * Called by initialise() and loadUrl() if there was a problem loading GML. - * @private - * @param {String} request + * + * Parameters: + * request - {String} */ requestFailure: function(request) { alert("Error in loading GML file "+this.url); diff --git a/lib/OpenLayers/Layer/GeoRSS.js b/lib/OpenLayers/Layer/GeoRSS.js index 7ef9ac8f04..3355083492 100644 --- a/lib/OpenLayers/Layer/GeoRSS.js +++ b/lib/OpenLayers/Layer/GeoRSS.js @@ -4,33 +4,52 @@ /** - * @class - * * @requires OpenLayers/Layer/Markers.js * @requires OpenLayers/Ajax.js + * + * Class: OpenLayers.Layer.GeoRSS + * Add GeoRSS Point features to your map. + * + * Inherits from: + * - + * - */ OpenLayers.Layer.GeoRSS = OpenLayers.Class.create(); OpenLayers.Layer.GeoRSS.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Markers, { - /** store url of text file - * @type str */ - location:null, + /** + * Property: location + * {String} store url of text file + */ + location: null, - /** @type Array(OpenLayers.Feature) */ - features: null, + /** + * Property: features + * Array({}) + */ + features: null, - /** @type OpenLayers.Feature */ - selectedFeature: null, + /** + * Property: selectedFeature + * {} + */ + selectedFeature: null, - /**@type OpenLayers.Icon */ + /** + * Property: icon + * {} + */ icon: null, /** - * @constructor + * Constructor: OpenLayers.Layer.GeoRSS + * Create a GeoRSS Layer. * - * @param {String} name - * @param {String} location + * Parameters: + * name - {String} + * location - {String} + * options - {Object} */ initialize: function(name, location, options) { OpenLayers.Layer.Markers.prototype.initialize.apply(this, [name, options]); @@ -40,7 +59,7 @@ OpenLayers.Layer.GeoRSS.prototype = }, /** - * + * Method: destroy */ destroy: function() { this.clearFeatures(); @@ -49,7 +68,11 @@ OpenLayers.Layer.GeoRSS.prototype = }, /** - * @param {XMLHttpRequest} ajaxRequest + * Method: parseData + * Parse the data returned from the Events call. + * + * Parameters: + * ajaxRequest - {XMLHttpRequest} */ parseData: function(ajaxRequest) { var doc = ajaxRequest.responseXML; @@ -171,7 +194,10 @@ OpenLayers.Layer.GeoRSS.prototype = }, /** - * @param {Event} evt + * Method: markerClick + * + * Parameters: + * evt - {Event} */ markerClick: function(evt) { sameMarkerClicked = (this == this.layer.selectedFeature); @@ -193,7 +219,8 @@ OpenLayers.Layer.GeoRSS.prototype = }, /** - * + * Method: clearFeatures + * Destroy all features in this layer. */ clearFeatures: function() { if (this.features != null) { @@ -208,5 +235,3 @@ OpenLayers.Layer.GeoRSS.prototype = /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.GeoRSS" }); - - diff --git a/lib/OpenLayers/Layer/Google.js b/lib/OpenLayers/Layer/Google.js index 26e9c83282..e449a56b20 100644 --- a/lib/OpenLayers/Layer/Google.js +++ b/lib/OpenLayers/Layer/Google.js @@ -4,35 +4,51 @@ /** - * @class - * * @requires OpenLayers/Layer/EventPane.js * @requires OpenLayers/Layer/FixedZoomLevels.js + * + * Class: OpenLayers.Layer.Gooogle + * + * Inherits: + * - + * - */ OpenLayers.Layer.Google = OpenLayers.Class.create(); OpenLayers.Layer.Google.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.EventPane, OpenLayers.Layer.FixedZoomLevels, { - /** @final @type int */ + /** + * Constant: MIN_ZOOM_LEVEL + * {Integer} 0 + */ MIN_ZOOM_LEVEL: 0, - /** @final @type int */ + /** + * Constant: MAX_ZOOM_LEVEL + * {Integer} 19 + */ MAX_ZOOM_LEVEL: 19, - /** Hardcode these resolutions so that they are more closely - * tied with the standard wms projection - * - * @final @type Array(float) */ + /** + * Constant: RESOLUTIONS + * {Array(Float)} Hardcode these resolutions so that they are more closely + * tied with the standard wms projection + */ RESOLUTIONS: [1.40625,0.703125,0.3515625,0.17578125,0.087890625,0.0439453125,0.02197265625,0.010986328125,0.0054931640625,0.00274658203125,0.001373291015625,0.0006866455078125,0.00034332275390625,0.000171661376953125,0.0000858306884765625,0.00004291534423828125,.00002145767211914062,.00001072883605957031,.00000536441802978515,.00000268220901489257], - /** @type GMapType */ + /** + * APIProperty: type + * {GMapType} + */ type: null, /** - * @constructor + * Constructor: OpenLayers.Layer.Google * - * @param {String} name + * Parameters: + * name - {String} + * options - {Object} */ initialize: function(name, options) { OpenLayers.Layer.EventPane.prototype.initialize.apply(this, arguments); @@ -41,10 +57,10 @@ OpenLayers.Layer.Google.prototype = this.addContainerPxFunction(); }, - /** Load the GMap and register appropriate event listeners. If we can't - * load GMap2, then display a warning message. - * - * @private + /** + * Method: loadMapObject + * Load the GMap and register appropriate event listeners. If we can't + * load GMap2, then display a warning message. */ loadMapObject:function() { @@ -75,12 +91,15 @@ OpenLayers.Layer.Google.prototype = }, - /** Overridden from EventPane because if a map type has been specified, - * we need to attach a listener for the first moveend -- this is how - * we will know that the map has been centered. Only once the map has - * been centered is it safe to change the gmap object's map type. + /** + * APIMethod: setMap + * Overridden from EventPane because if a map type has been specified, + * we need to attach a listener for the first moveend -- this is how + * we will know that the map has been centered. Only once the map has + * been centered is it safe to change the gmap object's map type. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.EventPane.prototype.setMap.apply(this, arguments); @@ -90,11 +109,11 @@ OpenLayers.Layer.Google.prototype = } }, - /** The map has been centered, and a map type was specified, so we - * set the map type on the gmap object, then unregister the listener - * so that we dont keep doing this every time the map moves. - * - * @private + /** + * Method: setMapType + * The map has been centered, and a map type was specified, so we + * set the map type on the gmap object, then unregister the listener + * so that we dont keep doing this every time the map moves. */ setMapType: function() { if (this.mapObject.getCenter() != null) { @@ -104,7 +123,10 @@ OpenLayers.Layer.Google.prototype = }, /** - * @param {Event} evt + * APIMethod: onMapResize + * + * Parameters: + * evt - {Event} */ onMapResize: function() { this.mapObject.checkResize(); @@ -112,11 +134,14 @@ OpenLayers.Layer.Google.prototype = /** - * @param {OpenLayers.Bounds} bounds - * - * @returns Corresponding zoom level for a specified Bounds. - * If mapObject is not loaded or not centered, returns null - * @type int + * APIMethod: getZoomForExtent + * + * Parameters: + * bounds - {} + * + * Return: + * {Integer} Corresponding zoom level for a specified Bounds. + * If mapObject is not loaded or not centered, returns null * getZoomForExtent: function (bounds) { var zoom = null; @@ -140,12 +165,15 @@ OpenLayers.Layer.Google.prototype = // /** - * @param {Object} moBounds + * APIMethod: getOLBoundsFromMapObjectBounds * - * @returns An OpenLayers.Bounds, translated from the passed-in - * MapObject Bounds - * Returns null if null value is passed in - * @type OpenLayers.Bounds + * Parameters: + * moBounds - {Object} + * + * Return: + * {} An , translated from the + * passed-in MapObject Bounds. + * Returns null if null value is passed in. */ getOLBoundsFromMapObjectBounds: function(moBounds) { var olBounds = null; @@ -161,11 +189,14 @@ OpenLayers.Layer.Google.prototype = }, /** - * @param {OpenLayers.Bounds} olBounds + * APIMethod: getMapObjectBoundsFromOLBounds * - * @returns A MapObject Bounds, translated from olBounds + * Parameters: + * olBounds - {} + * + * Return: + * {Object} A MapObject Bounds, translated from olBounds * Returns null if null value is passed in - * @type Object */ getMapObjectBoundsFromOLBounds: function(olBounds) { var moBounds = null; @@ -181,12 +212,15 @@ OpenLayers.Layer.Google.prototype = - /** Hack-on function because GMAPS does not give it to us + /** + * Method: addContainerPxFunction + * Hack-on function because GMAPS does not give it to us * - * @param {GLatLng} gLatLng - * - * @returns A GPoint specifying gLatLng translated into "Container" coords - * @type GPoint + * Parameters: + * gLatLng - {GLatLng} + * + * Return: + * {GPoint} A GPoint specifying gLatLng translated into "Container" coords */ addContainerPxFunction: function() { if (typeof GMap2 != "undefined" && !GMap2.fromLatLngToContainerPixel) { @@ -210,9 +244,11 @@ OpenLayers.Layer.Google.prototype = }, /** - * @return String with information on why layer is broken, how to get + * APIMethod: getWarningHTML + * + * Return: + * {String} String with information on why layer is broken, how to get * it working. - * @type String */ getWarningHTML:function() { @@ -245,26 +281,33 @@ OpenLayers.Layer.Google.prototype = // Get&Set Center, Zoom - /** Set the mapObject to the specified center and zoom + /** + * APIMethod: setMapObjectCenter + * Set the mapObject to the specified center and zoom * - * @param {Object} center MapObject LonLat format - * @param {int} zoom MapObject zoom format + * Parameters: + * center - {Object} MapObject LonLat format + * zoom - {int} MapObject zoom format */ setMapObjectCenter: function(center, zoom) { this.mapObject.setCenter(center, zoom); }, /** - * @returns the mapObject's current center in Map Object format - * @type Object + * APIMethod: getMapObjectCenter + * + * Return: + * {Object} The mapObject's current center in Map Object format */ getMapObjectCenter: function() { return this.mapObject.getCenter(); }, /** - * @returns the mapObject's current zoom, in Map Object format - * @type int + * APIMethod: getMapObjectZoom + * + * Return: + * {Integer} The mapObject's current zoom, in Map Object format */ getMapObjectZoom: function() { return this.mapObject.getZoom(); @@ -273,21 +316,27 @@ OpenLayers.Layer.Google.prototype = // LonLat - Pixel Translation - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectLonLatFromMapObjectPixel * - * @returns MapObject LonLat translated from MapObject Pixel - * @type Object + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Object} MapObject LonLat translated from MapObject Pixel */ getMapObjectLonLatFromMapObjectPixel: function(moPixel) { return this.mapObject.fromContainerPixelToLatLng(moPixel); }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectPixelFromMapObjectLonLat * - * @returns MapObject Pixel translated from MapObject LonLat - * @type Object + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Object} MapObject Pixel transtlated from MapObject LonLat */ getMapObjectPixelFromMapObjectLonLat: function(moLonLat) { return this.mapObject.fromLatLngToContainerPixel(moLonLat); @@ -297,10 +346,13 @@ OpenLayers.Layer.Google.prototype = // Bounds /** - * @param {Object} moBounds MapObject Bounds format + * APIMethod: getMapObjectZoomFromMapObjectBounds * - * @returns MapObject Zoom for specified MapObject Bounds - * @type Object + * Parameters: + * moBounds - {Object} MapObject Bounds format + * + * Return: + * {Object} MapObject Zoom for specified MapObject Bounds */ getMapObjectZoomFromMapObjectBounds: function(moBounds) { return this.mapObject.getBoundsZoomLevel(moBounds); @@ -316,31 +368,40 @@ OpenLayers.Layer.Google.prototype = // LonLat /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLongitudeFromMapObjectLonLat * - * @returns Longitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Longitude of the given MapObject LonLat */ getLongitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.lng(); }, /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLatitudeFromMapObjectLonLat * - * @returns Latitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Latitude of the given MapObject LonLat */ getLatitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.lat(); }, /** - * @param {int} lon float - * @param {int} lat float + * APIMethod: getMapObjectLonLatFromLonLat * - * @returns MapObject LonLat built from lon and lat params - * @type Object + * Parameters: + * lon - {Float} + * lat - {Float} + * + * Return: + * {Object} MapObject LonLat built from lon and lat params */ getMapObjectLonLatFromLonLat: function(lon, lat) { return new GLatLng(lat, lon); @@ -348,32 +409,41 @@ OpenLayers.Layer.Google.prototype = // Pixel - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getXFromMapObjectPixel * - * @returns X value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} X value of the MapObject Pixel */ getXFromMapObjectPixel: function(moPixel) { return moPixel.x; }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getYFromMapObjectPixel * - * @returns Y value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} Y value of the MapObject Pixel */ getYFromMapObjectPixel: function(moPixel) { return moPixel.y; }, - /** - * @param {int} x - * @param {int} y + /** + * APIMethod: getMapObjectPixelFromXY * - * @returns MapObject Pixel from x and y parameters - * @type Object + * Parameters: + * x - {Integer} + * y - {Integer} + * + * Return: + * {Object} MapObject Pixel from x and y parameters */ getMapObjectPixelFromXY: function(x, y) { return new GPoint(x, y); diff --git a/lib/OpenLayers/Layer/Grid.js b/lib/OpenLayers/Layer/Grid.js index 16b8dca2b2..47c72fecb9 100644 --- a/lib/OpenLayers/Layer/Grid.js +++ b/lib/OpenLayers/Layer/Grid.js @@ -4,32 +4,46 @@ /** - * @class - * * @requires OpenLayers/Layer/HTTPRequest.js + * + * Class: OpenLayers.Layer.Grid + * Base class for layers that use a lattice of tiles. Create a new grid + * layer with the constructor. + * + * Inherits from: + * - */ OpenLayers.Layer.Grid = OpenLayers.Class.create(); OpenLayers.Layer.Grid.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.HTTPRequest, { - /** @type OpenLayers.Size */ + /** + * APIProperty: tileSize + * {} + */ tileSize: null, - /** this is an array of rows, each row is an array of tiles - * - * @type Array(Array) */ + /** + * Property: grid + * {Array} This is an array of rows, each row is an array of tiles + */ grid: null, - /** @type Integer */ + /** + * APIProperty: buffer + * {Integer} + */ buffer: 2, /** - * @constructor - * - * @param {String} name - * @param {String} url - * @param {Object} params - * @param {Object} options Hashtable of extra options to tag onto the layer + * Constructor: OpenLayers.Layer.Grid + * Create a new grid layer + * + * Parameters: + * name - {String} + * url - {String} + * params - {Object} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, url, params, options) { OpenLayers.Layer.HTTPRequest.prototype.initialize.apply(this, @@ -37,8 +51,9 @@ OpenLayers.Layer.Grid.prototype = this.grid = new Array(); }, - /** on destroy, clear the grid. - * + /** + * APIMethod: destroy + * Deconstruct the layer and clear the grid. */ destroy: function() { this.clearGrid(); @@ -47,10 +62,10 @@ OpenLayers.Layer.Grid.prototype = OpenLayers.Layer.HTTPRequest.prototype.destroy.apply(this, arguments); }, - /** go through and remove all tiles from the grid, calling + /** + * Method: clearGrid + * Go through and remove all tiles from the grid, calling * destroy() on each of them to kill circular references - * - * @private */ clearGrid:function() { if (this.grid) { @@ -65,10 +80,14 @@ OpenLayers.Layer.Grid.prototype = }, /** - * @param {Object} obj + * APIMethod: clone + * Create a clone of this layer + * + * Parameters: + * obj - {Object} Is this ever used? * - * @returns An exact clone of this OpenLayers.Layer.Grid - * @type OpenLayers.Layer.Grid + * Return: + * {} An exact clone of this OpenLayers.Layer.Grid */ clone: function (obj) { @@ -93,10 +112,13 @@ OpenLayers.Layer.Grid.prototype = return obj; }, - /** When the layer is added to a map, then we can ask the map for + /** + * Method: setMap + * When the layer is added to a map, then we can ask the map for * its default tile size - * - * @param {OpenLayers.Map} map + * + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.HTTPRequest.prototype.setMap.apply(this, arguments); @@ -105,13 +127,16 @@ OpenLayers.Layer.Grid.prototype = } }, - /** This function is called whenever the map is moved. All the moving + /** + * Method: moveTo + * This function is called whenever the map is moved. All the moving * of actual 'tiles' is done by the map, but moveTo's role is to accept * a bounds and make sure the data that that bounds requires is pre-loaded. - * - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { OpenLayers.Layer.HTTPRequest.prototype.moveTo.apply(this, arguments); @@ -157,12 +182,13 @@ OpenLayers.Layer.Grid.prototype = }, /** - * @private + * Method: getGridBounds + * Get the bounds of the grid * - * @returns A Bounds object representing the bounds of all the currently - * loaded tiles (including those partially or not at all seen - * onscreen) - * @type OpenLayers.Bounds + * Return: + * {} A Bounds object representing the bounds of all the + * currently loaded tiles (including those partially or not at all seen + * onscreen) */ getGridBounds:function() { @@ -179,7 +205,8 @@ OpenLayers.Layer.Grid.prototype = }, /** - * @private + * Method: _initTiles + * Initialize the tiles */ _initTiles:function() { @@ -280,9 +307,8 @@ OpenLayers.Layer.Grid.prototype = this.spiralTileLoad(); }, - /** - * @private - * + /** + * Method: spiralTileLoad * Starts at the top right corner of the grid and proceeds in a spiral * towards the center, adding tiles one at a time to the beginning of a * queue. @@ -355,23 +381,27 @@ OpenLayers.Layer.Grid.prototype = }, /** - * addTile gives subclasses of Grid the opportunity to create an + * APIMethod: addTile + * Gives subclasses of Grid the opportunity to create an * OpenLayer.Tile of their choosing. The implementer should initialize * the new tile and take whatever steps necessary to display it. * - * @param {OpenLayers.Bounds} bounds + * Parameters + * bounds - {} * - * @returns The added OpenLayers.Tile - * @type OpenLayers.Tile + * Return: + * {} The added OpenLayers.Tile */ addTile:function(bounds, position) { // Should be implemented by subclasses }, /** + * APIMethod: mergeNewParams * Once params have been changed, we will need to re-init our tiles * - * @param {Object} newParams Hashtable of new params to use + * Parameters: + * newParams - {Object} Hashtable of new params to use */ mergeNewParams:function(newArguments) { OpenLayers.Layer.HTTPRequest.prototype.mergeNewParams.apply(this, @@ -384,9 +414,11 @@ OpenLayers.Layer.Grid.prototype = /** - * @private - * - * @param {Boolean} prepend if true, prepend to beginning. + * Method: shiftRow + * Shifty grid work + * + * Parameters: + * prepend - {Boolean} if true, prepend to beginning. * if false, then append to end */ shiftRow:function(prepend) { @@ -417,9 +449,11 @@ OpenLayers.Layer.Grid.prototype = }, /** - * @private - * - * @param {Boolean} prepend if true, prepend to beginning. + * Method: shiftColumn + * Shift grid work in the other dimension + * + * Parameters: + * prepend - {Boolean} if true, prepend to beginning. * if false, then append to end */ shiftColumn: function(prepend) { @@ -448,6 +482,9 @@ OpenLayers.Layer.Grid.prototype = } }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of this class + */ CLASS_NAME: "OpenLayers.Layer.Grid" }); diff --git a/lib/OpenLayers/Layer/HTTPRequest.js b/lib/OpenLayers/Layer/HTTPRequest.js index 08070377ec..30e6620678 100644 --- a/lib/OpenLayers/Layer/HTTPRequest.js +++ b/lib/OpenLayers/Layer/HTTPRequest.js @@ -4,47 +4,54 @@ /** - * @class - * * @requires OpenLayers/Layer.js + * + * Class: OpenLayers.Layer.HTTPRequest + * + * Inherits: + * - OpenLayers.Layer */ OpenLayers.Layer.HTTPRequest = OpenLayers.Class.create(); OpenLayers.Layer.HTTPRequest.prototype = OpenLayers.Class.inherit( OpenLayers.Layer, { - /** Used to hash URL param strings for multi-WMS server selection. - * Set to the Golden Ratio per Knuth's recommendation. - * - * @final @type Numeric + /** + * Constant: URL_HASH_FACTOR + * {Float} Used to hash URL param strings for multi-WMS server selection. + * Set to the Golden Ratio per Knuth's recommendation. */ URL_HASH_FACTOR: (Math.sqrt(5) - 1) / 2, - /** This is either an array of url strings or a single url string. - * - * @type Array(String) or String */ + /** + * Property: url + * {Array(String) or String} This is either an array of url strings or + * a single url string. + */ url: null, - /** Hashtable of key/value parameters - * - * @type Object */ + /** + * Property: params + * {Object} Hashtable of key/value parameters + */ params: null, - /** Whether layer should reproject itself based on base layer locations. - * This allows reprojection onto commercial layers. Default is false: - * Most layers can't reproject, but layers which can create non-square - * geographic pixels can, like WMS. - * - * @type Boolean + /** + * APIProperty: reproject + * {Boolean} Whether layer should reproject itself based on base layer + * locations. This allows reprojection onto commercial layers. + * Default is false: Most layers can't reproject, but layers + * which can create non-square geographic pixels can, like WMS. */ reproject: false, /** - * @constructor + * Constructor: OpenLayers.Layer.HTTPRequest * - * @param {String} name - * @param {Array(String) or String} url - * @param {Object} params - * @param {Object} options Hashtable of extra options to tag onto the layer + * Parameters: + * name - {String} + * url - {Array(String) or String} + * params - {Object} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, url, params, options) { var newArguments = arguments; @@ -55,7 +62,7 @@ OpenLayers.Layer.HTTPRequest.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { this.url = null; @@ -64,10 +71,14 @@ OpenLayers.Layer.HTTPRequest.prototype = }, /** - * @param {Object} obj + * APIMethod: clone * - * @returns An exact clone of this OpenLayers.Layer.HTTPRequest - * @type OpenLayers.Layer.HTTPRequest + * Parameters: + * obj - {Object} + * + * Return: + * {} An exact clone of this + * */ clone: function (obj) { @@ -87,33 +98,40 @@ OpenLayers.Layer.HTTPRequest.prototype = }, /** - * @param {String} newUrl + * APIMethod: setUrl + * + * Parameters: + * newUrl - {String} */ setUrl: function(newUrl) { this.url = newUrl; }, /** - * @param {Object} newParams + * APIMethod: mergeNewParams + * + * Parameters: + * newParams - {Object} */ mergeNewParams:function(newParams) { this.params = OpenLayers.Util.extend(this.params, newParams); }, /** + * Method: selectUrl * selectUrl() implements the standard floating-point multiplicative - * hash function described by Knuth, and hashes the contents of the - * given param string into a float between 0 and 1. This float is then - * scaled to the size of the provided urls array, and used to select - * a URL. + * hash function described by Knuth, and hashes the contents of the + * given param string into a float between 0 and 1. This float is then + * scaled to the size of the provided urls array, and used to select + * a URL. * - * @param {String} paramString - * @param {Array(String)} urls - * - * @returns An entry from the urls array, deterministically selected based - * on the paramString. - * @type String + * Parameters: + * paramString - {String} + * urls - {Array(String)} * + * Return: + * {String} An entry from the urls array, deterministically selected based + * on the paramString. */ selectUrl: function(paramString, urls) { var product = 1; @@ -124,7 +142,9 @@ OpenLayers.Layer.HTTPRequest.prototype = return urls[Math.floor(product * urls.length)]; }, - /** combine url with layer's params and these newParams. + /** + * Method: getFullRequestString + * Combine url with layer's params and these newParams. * * does checking on the serverPath variable, allowing for cases when it * is supplied with trailing ? or &, as well as cases where not. @@ -134,11 +154,12 @@ OpenLayers.Layer.HTTPRequest.prototype = * * WARNING: The altUrl parameter is deprecated and will be removed in 3.0. * - * @param {Object} newParams - * @param {String} altUrl Use this as the url instead of the layer's url + * Parameters: + * newParams - {Object} + * altUrl - {String} Use this as the url instead of the layer's url * - * - * @type String + * Return: + * {String} */ getFullRequestString:function(newParams, altUrl) { diff --git a/lib/OpenLayers/Layer/Image.js b/lib/OpenLayers/Layer/Image.js index cdf37aa0ef..81b7142c10 100644 --- a/lib/OpenLayers/Layer/Image.js +++ b/lib/OpenLayers/Layer/Image.js @@ -3,57 +3,67 @@ * for the full text of the license. */ /** - * @fileoverview Image Layer - * @author Tim Schaub - */ - -/** - * @class - * * @requires OpenLayers/Layer.js * @requires OpenLayers/Tile/Image.js + * + * Class: OpenLayers.Layer.Image + * Instances of OpenLayers.Layer.Image are used to display data from a web + * accessible image as a map layer. Create a new image layer with the + * constructor. Inherits from . */ OpenLayers.Layer.Image = OpenLayers.Class.create(); OpenLayers.Layer.Image.prototype = OpenLayers.Class.inherit(OpenLayers.Layer, { - /** By default, Layer.Image will be a baselayer - * - * @type Boolean */ + /** + * Property: isBaseLayer + * {Boolean} The layer is a base layer. Default is true. Set this property + * in the layer options + */ isBaseLayer: true, - /** @type String */ + /** + * Property: url + * {String} URL of the image to use + */ url: null, /** - * The image bounds in map units - * @type OpenLayers.Bounds + * Property: extent + * {} The image bounds in map units */ extent: null, /** - * The image size in pixels - * @type OpenLayers.Size + * Property: size + * {} The image size in pixels */ size: null, - /** @type OpenLayers.Tile.Image */ + /** + * Property: tile + * {} + */ tile: null, /** - * The ratio of height/width represented by a single pixel in the graphic - * @type Float */ + * Property: aspectRatio + * {Float} The ratio of height/width represented by a single pixel in the + * graphic + */ aspectRatio: null, /** - * @constructor - * - * @param {String} name - * @param {String} url Relative or absolute path to the image - * @param {OpenLayers.Bounds} extent The extent represented by the image - * @param {OpenLayers.Size} size The size (in pixels) of the image - * @param {Object} options Hashtable of extra options to tag onto the layer - */ + * Constructor: OpenLayers.Layer.Image + * Create a new image layer + * + * Parameters: + * name - {String} A name for the layer. + * url - {String} Relative or absolute path to the image + * extent - {} The extent represented by the image + * size - {} The size (in pixels) of the image + * options - {Object} Hashtable of extra options to tag onto the layer + */ initialize: function(name, url, extent, size, options) { this.url = url; this.extent = extent; @@ -65,7 +75,8 @@ OpenLayers.Layer.Image.prototype = }, /** - * + * Method: destroy + * Destroy this layer */ destroy: function() { if (this.tile) { @@ -76,10 +87,14 @@ OpenLayers.Layer.Image.prototype = }, /** - * @param {Object} obj - * - * @returns An exact clone of this OpenLayers.Layer.Image - * @type OpenLayers.Layer.Image + * Method: clone + * Create a clone of this layer + * + * Paramters: + * obj - {Object} An optional layer (is this ever used?) + * + * Return: + * {} An exact copy of this layer */ clone: function(obj) { @@ -100,7 +115,10 @@ OpenLayers.Layer.Image.prototype = }, /** - * @param {OpenLayers.Map} map + * APIMethod: setMap + * + * Parameters: + * map - {} */ setMap: function(map) { /** @@ -117,11 +135,14 @@ OpenLayers.Layer.Image.prototype = OpenLayers.Layer.prototype.setMap.apply(this, arguments); }, - /** Create the tile for the image or resize it for the new resolution + /** + * Method: moveTo + * Create the tile for the image or resize it for the new resolution * - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { OpenLayers.Layer.prototype.moveTo.apply(this, arguments); @@ -163,23 +184,32 @@ OpenLayers.Layer.Image.prototype = }, /** - * @param {String} newUrl + * APIMethod: setUrl + * + * Parameters: + * newUrl - {String} */ setUrl: function(newUrl) { this.url = newUrl; this.draw(); }, - /** The url we return is always the same (the image itself never changes) - * so we can ignore the bounds parameter (it will always be the same, - * anyways) + /** + * APIMethod: getURL + * The url we return is always the same (the image itself never changes) + * so we can ignore the bounds parameter (it will always be the same, + * anyways) * - * @param {OpenLayers.Bounds} bounds + * Parameters: + * bounds - {} */ getURL: function(bounds) { return this.url; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} OpenLayers.Layer.Image + */ CLASS_NAME: "OpenLayers.Layer.Image" }); diff --git a/lib/OpenLayers/Layer/KaMap.js b/lib/OpenLayers/Layer/KaMap.js index 3d6530c51e..85441c5626 100644 --- a/lib/OpenLayers/Layer/KaMap.js +++ b/lib/OpenLayers/Layer/KaMap.js @@ -4,29 +4,53 @@ /** - * @class - * * @requires OpenLayers/Layer/Grid.js + * + * Class: OpenLayers.Layer.KaMap + * + * Inherits: + * - */ OpenLayers.Layer.KaMap = OpenLayers.Class.create(); OpenLayers.Layer.KaMap.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Grid, { - /** KaMap Layer is always a base layer - * - * @type Boolean + /** + * APIProperty: isBaseLayer + * {Boolean} KaMap Layer is always a base layer */ isBaseLayer: true, - + + /** + * APIProperty: units + * {?} + */ units: null, + /** + * APIProperty: resolution + * {Float} + */ resolution: OpenLayers.DOTS_PER_INCH, + /** + * Constant: DEFAULT_PARAMS + * {Object} + */ DEFAULT_PARAMS: { i: 'jpeg', map: '' }, + /** + * Constructor: OpenLayers.Layer.KaMap + * + * Parameters: + * name - {String} + * url - {String} + * params - {Object} + * options - {Object} + */ initialize: function(name, url, params, options) { var newArguments = new Array(); newArguments.push(name, url, params, options); @@ -41,12 +65,15 @@ OpenLayers.Layer.KaMap.prototype = }, /** - * @param {OpenLayers.Bounds} bounds + * Method: getURL * - * @returns A string with the layer's url and parameters and also the - * passed-in bounds and appropriate tile size specified as - * parameters - * @type String + * Parameters: + * bounds - {} + * + * Return: + * {String} A string with the layer's url and parameters and also the + * passed-in bounds and appropriate tile size specified as + * parameters */ getURL: function (bounds) { bounds = this.adjustBounds(bounds); @@ -60,13 +87,26 @@ OpenLayers.Layer.KaMap.prototype = s: scale }); }, - + + /** + * Method: addTile + * + * Parameters: + * bounds - {} + * position - {} + * + * Return: + * {} + */ addTile:function(bounds,position) { var url = this.getURL(bounds); return new OpenLayers.Tile.Image(this, position, bounds, url, this.tileSize); }, - + + /** + * Method: _initTiles + */ _initTiles:function() { var viewSize = this.map.getSize(); @@ -148,10 +188,13 @@ OpenLayers.Layer.KaMap.prototype = }, /** - * @param {Object} obj + * APIMethod: clone * - * @returns An exact clone of this OpenLayers.Layer.Grid - * @type OpenLayers.Layer.Grid + * Parameters: + * obj - {Object} + * + * Return: + * {} An exact clone of this OpenLayers.Layer.KaMap */ clone: function (obj) { @@ -176,7 +219,6 @@ OpenLayers.Layer.KaMap.prototype = return obj; }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.KaMap" }); diff --git a/lib/OpenLayers/Layer/MapServer.js b/lib/OpenLayers/Layer/MapServer.js index cca83298a9..d8595f515b 100644 --- a/lib/OpenLayers/Layer/MapServer.js +++ b/lib/OpenLayers/Layer/MapServer.js @@ -3,26 +3,50 @@ * for the full text of the license. */ // @requires OpenLayers/Layer/Grid.js /** -* @class * @requires OpenLayers/Layer/Grid.js -*/ + * + * Class: OpenLayers.Layer.MapServer + * Instances of OpenLayers.Layer.MapServer are used to display + * data from a MapServer CGI instance. + * + * Inherits from: + * - + */ OpenLayers.Layer.MapServer = OpenLayers.Class.create(); OpenLayers.Layer.MapServer.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Grid, { - /** @final @type hash */ + /** + * Constant: DEFAULT_PARAMS + * {Object} Hashtable of default parameter key/value pairs + */ DEFAULT_PARAMS: { mode: "map", map_imagetype: "png" }, - /** - * @constructor - * - * @param {str} name - * @param {str} url - * @param {hash} params - */ + /** + * Constructor: OpenLayers.Layer.MapServer + * Create a new MapServer layer object + * + * Example: + * (code) + * layer = new OpenLayers.Layer.MapServer( "OpenLayers WMS", + * "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'}, + * {gutter: 15}); + * (end) + * + * Parameters: + * name - {String} A name for the layer + * url - {String} Base url for the MapServer CGI + * (e.g. http://www2.dmsolutions.ca/cgi-bin/mapserv) + * params - {Object} An object with key/value pairs representing the + * GetMap query string parameters and parameter values. + * options - {Ojbect} Hashtable of extra options to tag onto the layer + * + * Return: + * A new OpenLayers.Layer.MapServer instance + */ initialize: function(name, url, params, options) { var newArguments = new Array(); newArguments.push(name, url, params, options); @@ -44,11 +68,12 @@ OpenLayers.Layer.MapServer.prototype = }, /** - * @param {Object} obj - * - * @returns A clone of this OpenLayers.Layer.MapServer - * @type OpenLayers.Layer.MapServer - */ + * Method: clone + * Create a clone of this layer + * + * Return: + * {} An exact clone of this layer + */ clone: function (obj) { if (obj == null) { obj = new OpenLayers.Layer.MapServer(this.name, @@ -65,10 +90,10 @@ OpenLayers.Layer.MapServer.prototype = }, /** - * addTile creates a tile, initializes it (via 'draw' in this case), and - * adds it to the layer div. + * addTile creates a tile, initializes it, and + * adds it to the layer div. * - * @param {OpenLayers.Bounds} bounds + * @param {} bounds * * @returns The added OpenLayers.Tile.Image * @type OpenLayers.Tile.Image @@ -79,12 +104,16 @@ OpenLayers.Layer.MapServer.prototype = }, /** - * @param {OpenLayers.Bounds} bounds - * - * @returns A string with the layer's url and parameters and also the - * passed-in bounds and appropriate tile size specified as - * parameters - * @type String + * Method: getURL + * Return a query string for this layer + * + * Parameters: + * bounds - {} A bounds representing the bbox for the + * request + * + * Return: + * {String} A string with the layer's url and parameters and also the + * passed-in bounds and appropriate tile size specified as parameters */ getURL: function (bounds) { bounds = this.adjustBounds(bounds); @@ -105,17 +134,20 @@ OpenLayers.Layer.MapServer.prototype = }, /** - * getFullRequestString on MapServer layers is special, because we - * do a regular expression replace on ',' in parameters to '+'. - * This is why it is subclassed here. - * - * @param {Object} newParams Parameters to add to the default parameters - * for the layer. - * @param {String} altUrl Alternative base URL to use. - */ + * Method: getFullRequestString + * combine the layer's url with its params and these newParams. + * + * Parameter: {Object} newParams + * new parameters that should be added to the request string. + * + * Parameter: {String} altUrl + * optional, replace the URL in the full request string with the + * provided URL. + * + * Return: {String} + * A string with the layer's url and parameters embedded in it. + */ getFullRequestString:function(newParams, altUrl) { - - // use layer's url unless altUrl passed in var url = (altUrl == null) ? this.url : altUrl; @@ -166,6 +198,9 @@ OpenLayers.Layer.MapServer.prototype = } return requestString; }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} OpenLayers.Layer.MapServer + */ CLASS_NAME: "OpenLayers.Layer.MapServer" }); diff --git a/lib/OpenLayers/Layer/MapServer/Untiled.js b/lib/OpenLayers/Layer/MapServer/Untiled.js index db75cce653..093e6b62fb 100644 --- a/lib/OpenLayers/Layer/MapServer/Untiled.js +++ b/lib/OpenLayers/Layer/MapServer/Untiled.js @@ -2,44 +2,60 @@ * See http://svn.openlayers.org/trunk/openlayers/release-license.txt * for the full text of the license. */ -/* Derived from the WMS/Untiled.js script by Stephen Woodbridge, 2007 */ - - /** - * @class - * * @requires OpenLayers/Layer/HTTPRequest.js * @requires OpenLayers/Layer/MapServer.js + * + * Class: OpenLayers.Layer.MapServer.Untiled + * + * Inherits from: + * - */ OpenLayers.Layer.MapServer.Untiled = OpenLayers.Class.create(); OpenLayers.Layer.MapServer.Untiled.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.HTTPRequest, { - /** Hashtable of default parameter key/value pairs - * @final @type Object */ + /** + * Constant: default_params + * Hashtable of default parameter key/value pairs + */ default_params: { mode: "map", map_imagetype: "png" }, + + /** + * APIProperty: reproject + * {Boolean} 'stretch' tiles according to base layer. + */ reproject: true, - /** the ratio of image/tile size to map size (this is the untiled buffer) - * @type int */ + /** + * APIProperty: ratio + * {Float} the ratio of image/tile size to map size (this is the untiled + * buffer) + */ ratio: 1, - /** @type OpenLayers.Tile.Image */ + /** + * Property: tile + * {} + */ tile: null, - /** did the image finish loading before a new draw was initiated? - * @type Boolean */ + /** + * Propety: doneLoading + * {Boolean} did the image finish loading before a new draw was initiated? + */ doneLoading: false, /** - * @constructor + * Constructor: OpenLayers.Layer.MapServer.Untiled * - * @param {String} name - * @param {String} url - * @param {Object} params + * Parameters: + * name - {String} + * url - {String} + * params - {Object} */ initialize: function(name, url, params, options) { var newArguments = []; @@ -60,7 +76,7 @@ OpenLayers.Layer.MapServer.Untiled.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { if (this.tile) { @@ -71,10 +87,12 @@ OpenLayers.Layer.MapServer.Untiled.prototype = }, /** - * @param {Object} obj + * APIMethod: clone + * obj - {Object} * - * @returns An exact clone of this OpenLayers.Layer.MapServer.Untiled - * @type OpenLayers.Layer.MapServer.Untiled + * Returns: + * {} An exact clone of this + * OpenLayers.Layer.MapServer.Untiled */ clone: function (obj) { @@ -94,15 +112,19 @@ OpenLayers.Layer.MapServer.Untiled.prototype = }, - /** Once HTTPRequest has set the map, we can load the image div + /** + * Method: setMap + * Once HTTPRequest has set the map, we can load the image div * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.HTTPRequest.prototype.setMap.apply(this, arguments); }, /** + * Method: setTileSize * Set the tile size based on the map size. This also sets layer.imageSize * and layer.imageOffset for use by Tile.Image. */ @@ -115,12 +137,15 @@ OpenLayers.Layer.MapServer.Untiled.prototype = this.imageOffset = new OpenLayers.Pixel(0, 0); }, - /** When it is not a dragging move (ie when done dragging) + /** + * Method: moveTo + * When it is not a dragging move (ie when done dragging) * reload and recenter the div. - * - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { if (!this.doneLoading) { @@ -190,7 +215,13 @@ OpenLayers.Layer.MapServer.Untiled.prototype = } }, - + + /** + * Method: getURL + * + * Parameters: + * bounds - {} + */ getURL: function(bounds) { var url = this.getFullRequestString( {mapext:bounds.toBBOX().replace(/,/g," "), @@ -204,16 +235,24 @@ OpenLayers.Layer.MapServer.Untiled.prototype = }, - /** Once HTTPRequest has updated the url, reload the image div - * @param {String} newUrl + /** + * APIMehod: setUrl + * Once HTTPRequest has updated the url, reload the image div + * + * Parameters: + * newUrl - {String} */ setUrl: function(newUrl) { OpenLayers.Layer.HTTPRequest.prototype.setUrl.apply(this, arguments); this.moveTo(); }, - /** Once HTTPRequest has updated new params, reload the image div - * @param {Object} newParams + /** + * APIMethod: mergeNewParams + * Once HTTPRequest has updated new params, reload the image div + * + * Parameters: + * newParams - {Object} */ mergeNewParams:function(newParams) { OpenLayers.Layer.HTTPRequest.prototype.mergeNewParams.apply(this, @@ -222,15 +261,16 @@ OpenLayers.Layer.MapServer.Untiled.prototype = this.moveTo(null, true); }, - /** combine the layer's url with its params and these newParams. + /** + * APIMethod: getFullRequestString + * combine the layer's url with its params and these newParams. * * Add the SRS parameter from 'projection' -- this is probably * more eloquently done via a setProjection() method, but this * works for now and always. - * - * @param {Object} newParams - * - * @type String + * + * Parameters: + * newParams - {Object} */ getFullRequestString:function(newParams) { var projection = this.map.getProjection(); diff --git a/lib/OpenLayers/Layer/Markers.js b/lib/OpenLayers/Layer/Markers.js index 5ecea4b9fb..c38284521c 100644 --- a/lib/OpenLayers/Layer/Markers.js +++ b/lib/OpenLayers/Layer/Markers.js @@ -4,38 +4,43 @@ /** - * @class - * - * @requires OpenLayers/Layer.js + * Class: OpenLayers.Layer.Markers + * Inherits from: + * - */ OpenLayers.Layer.Markers = OpenLayers.Class.create(); OpenLayers.Layer.Markers.prototype = OpenLayers.Class.inherit( OpenLayers.Layer, { - /** Markers layer is never a base layer. - * - * @type Boolean - */ - isBaseLayer: false, + /** + * Property: isBaseLayer + * {Boolean} Markers layer is never a base layer. + */ + isBaseLayer: false, - /** internal marker list - * @type Array(OpenLayers.Marker) */ - markers: null, + /** + * Property: markers + * Array({}) internal marker list + */ + markers: null, - /** internal state of drawing. This is a workaround for the fact - * that the map does not call moveTo with a zoomChanged when the - * map is first starting up. This lets us catch the case where we - * have *never* drawn the layer, and draw it even if the zoom hasn't - * changed. - * @type Boolean */ - drawn: false, + /** + * Property: drawn + * {Boolean} internal state of drawing. This is a workaround for the fact + * that the map does not call moveTo with a zoomChanged when the map is + * first starting up. This lets us catch the case where we have *never* + * drawn the layer, and draw it even if the zoom hasn't changed. + */ + drawn: false, /** - * @constructor + * Constructor: OpenLayers.Layer.Markers + * Create a Markers layer. * - * @param {String} name - * @param {Object} options Hashtable of extra options to tag onto the layer + * Parameters: + * name - {String} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, options) { OpenLayers.Layer.prototype.initialize.apply(this, arguments); @@ -43,7 +48,7 @@ OpenLayers.Layer.Markers.prototype = }, /** - * + * Method: destroy */ destroy: function() { this.clearMarkers(); @@ -53,9 +58,12 @@ OpenLayers.Layer.Markers.prototype = /** - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * Method: moveTo + * + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { OpenLayers.Layer.prototype.moveTo.apply(this, arguments); @@ -67,7 +75,10 @@ OpenLayers.Layer.Markers.prototype = }, /** - * @param {OpenLayers.Marker} marker + * Method: addMarker + * + * Parameters: + * marker - {} */ addMarker: function(marker) { this.markers.push(marker); @@ -78,7 +89,10 @@ OpenLayers.Layer.Markers.prototype = }, /** - * @param {OpenLayers.Marker} marker + * Method: removeMarker + * + * Parameters: + * marker - {} */ removeMarker: function(marker) { OpenLayers.Util.removeItem(this.markers, marker); @@ -89,7 +103,7 @@ OpenLayers.Layer.Markers.prototype = }, /** - * + * Method: clearMarkers */ clearMarkers: function() { if (this.markers != null) { @@ -99,7 +113,9 @@ OpenLayers.Layer.Markers.prototype = } }, - /** clear all the marker div's from the layer and then redraw all of them. + /** + * Method: redraw + * clear all the marker div's from the layer and then redraw all of them. * Use the map to recalculate new placement of markers. */ redraw: function() { @@ -108,12 +124,13 @@ OpenLayers.Layer.Markers.prototype = } }, - /** Calculate the pixel location for the marker, create it, and + /** + * Method: drawMarker + * *Private*. Calculate the pixel location for the marker, create it, and * add it to the layer's div - * - * @private - * - * @param {OpenLayers.Marker} marker + * + * Parameters: + * marker - {} */ drawMarker: function(marker) { var px = this.map.getLayerPxFromLonLat(marker.lonlat); diff --git a/lib/OpenLayers/Layer/MultiMap.js b/lib/OpenLayers/Layer/MultiMap.js index 44cdb72890..42836bf942 100644 --- a/lib/OpenLayers/Layer/MultiMap.js +++ b/lib/OpenLayers/Layer/MultiMap.js @@ -3,35 +3,51 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Layer/EventPane.js * @requires OpenLayers/Layer/FixedZoomLevels.js + * + * Class: OpenLayers.Layer.MultiMap + * + * Inherits: + * - + * - */ OpenLayers.Layer.MultiMap = OpenLayers.Class.create(); OpenLayers.Layer.MultiMap.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.EventPane, OpenLayers.Layer.FixedZoomLevels, { - /** @final @type int */ + /** + * Constant: MIN_ZOOM_LEVEL + * {Integer} 1 + */ MIN_ZOOM_LEVEL: 1, - /** @final @type int */ + /** + * Constant: MAX_ZOOM_LEVEL + * {Integer} 17 + */ MAX_ZOOM_LEVEL: 17, - /** Hardcode these resolutions so that they are more closely - * tied with the standard wms projection - * - * @final @type Array(float) */ + /** + * Constant: RESOLUTIONS + * {Array(Float)} Hardcode these resolutions so that they are more closely + * tied with the standard wms projection + */ RESOLUTIONS: [9, 1.40625,0.703125,0.3515625,0.17578125,0.087890625,0.0439453125,0.02197265625,0.010986328125,0.0054931640625,0.00274658203125,0.001373291015625,0.0006866455078125,0.00034332275390625,0.000171661376953125,0.0000858306884765625,0.00004291534423828125], - /** @type VEMapType */ + /** + * APIProperty: type + * {?} + */ type: null, /** - * @constructor + * Constructor: OpenLayers.Layer.MultiMap * - * @param {String} name + * Parameters: + * name - {String} + * options - {Object} */ initialize: function(name, options) { OpenLayers.Layer.EventPane.prototype.initialize.apply(this, arguments); @@ -40,7 +56,7 @@ OpenLayers.Layer.MultiMap.prototype = }, /** - * + * Method: loadMapObject */ loadMapObject:function() { try { //crash proofing @@ -49,9 +65,11 @@ OpenLayers.Layer.MultiMap.prototype = }, /** - * @return String with information on why layer is broken, how to get + * APIMethod: getWarningHTML + * + * Return: + * {String} String with information on why layer is broken, how to get * it working. - * @type String */ getWarningHTML:function() { @@ -84,26 +102,33 @@ OpenLayers.Layer.MultiMap.prototype = // Get&Set Center, Zoom - /** Set the mapObject to the specified center and zoom + /** + * APIMethod: setMapObjectCenter + * Set the mapObject to the specified center and zoom * - * @param {Object} center MapObject LonLat format - * @param {int} zoom MapObject zoom format + * Parameters: + * center - {Object} MapObject LonLat format + * zoom - {int} MapObject zoom format */ setMapObjectCenter: function(center, zoom) { this.mapObject.goToPosition(center, zoom); }, /** - * @returns the mapObject's current center in Map Object format - * @type Object + * APIMethod: getMapObjectCenter + * + * Return: + * {Object} The mapObject's current center in Map Object format */ getMapObjectCenter: function() { return this.mapObject.getCurrentPosition(); }, /** - * @returns the mapObject's current zoom, in Map Object format - * @type int + * APIMethod: getMapObjectZoom + * + * Return: + * {Integer} The mapObject's current zoom, in Map Object format */ getMapObjectZoom: function() { return this.mapObject.getZoomFactor(); @@ -112,11 +137,14 @@ OpenLayers.Layer.MultiMap.prototype = // LonLat - Pixel Translation - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectLonLatFromMapObjectPixel * - * @returns MapObject LonLat translated from MapObject Pixel - * @type Object + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Object} MapObject LonLat translated from MapObject Pixel */ getMapObjectLonLatFromMapObjectPixel: function(moPixel) { moPixel.x = moPixel.x - (this.map.getSize().w/2); @@ -124,11 +152,14 @@ OpenLayers.Layer.MultiMap.prototype = return this.mapObject.getMapPositionAt(moPixel); }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectPixelFromMapObjectLonLat * - * @returns MapObject Pixel translated from MapObject LonLat - * @type Object + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Object} MapObject Pixel transtlated from MapObject LonLat */ getMapObjectPixelFromMapObjectLonLat: function(moLonLat) { return this.mapObject.geoPosToContainerPixels(moLonLat); @@ -145,31 +176,40 @@ OpenLayers.Layer.MultiMap.prototype = // LonLat /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLongitudeFromMapObjectLonLat * - * @returns Longitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Longitude of the given MapObject LonLat */ getLongitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.lon; }, /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLatitudeFromMapObjectLonLat * - * @returns Latitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Latitude of the given MapObject LonLat */ getLatitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.lat; }, /** - * @param {int} lon float - * @param {int} lat float + * APIMethod: getMapObjectLonLatFromLonLat * - * @returns MapObject LonLat built from lon and lat params - * @type Object + * Parameters: + * lon - {Float} + * lat - {Float} + * + * Return: + * {Object} MapObject LonLat built from lon and lat params */ getMapObjectLonLatFromLonLat: function(lon, lat) { return new MMLatLon(lat, lon); @@ -177,38 +217,46 @@ OpenLayers.Layer.MultiMap.prototype = // Pixel - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getXFromMapObjectPixel * - * @returns X value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} X value of the MapObject Pixel */ getXFromMapObjectPixel: function(moPixel) { return moPixel.x; }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getYFromMapObjectPixel * - * @returns Y value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} Y value of the MapObject Pixel */ getYFromMapObjectPixel: function(moPixel) { return moPixel.y; }, - /** - * @param {int} x - * @param {int} y + /** + * APIMethod: getMapObjectPixelFromXY * - * @returns MapObject Pixel from x and y parameters - * @type Object + * Parameters: + * x - {Integer} + * y - {Integer} + * + * Return: + * {Object} MapObject Pixel from x and y parameters */ getMapObjectPixelFromXY: function(x, y) { return new MMPoint(x, y); }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.MultiMap" }); diff --git a/lib/OpenLayers/Layer/TMS.js b/lib/OpenLayers/Layer/TMS.js index cce60e73ea..4324c7278d 100644 --- a/lib/OpenLayers/Layer/TMS.js +++ b/lib/OpenLayers/Layer/TMS.js @@ -4,27 +4,44 @@ /** - * @class - * * @requires OpenLayers/Layer/Grid.js + * + * Class: OpenLayers.Layer.TMS + * + * Inherits: + * - */ OpenLayers.Layer.TMS = OpenLayers.Class.create(); OpenLayers.Layer.TMS.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Grid, { - + /** + * APIProperty: reproject + * {Boolean} + */ reproject: false, + + /** + * APIProperty: isBaseLayer + * {Boolean} + */ isBaseLayer: true, + + /** + * APIProperty: tileOrigin + * {} + */ tileOrigin: null, /** - * @constructor - * - * @param {String} name - * @param {String} url - * @param {Object} params - * @param {Object} options Hashtable of extra options to tag onto the layer - */ + * Constructor: OpenLayers.Layer.TMS + * + * Parameters: + * name - {String} + * url - {String} + * params - {Object} + * options - {Object} Hashtable of extra options to tag onto the layer + */ initialize: function(name, url, options) { var newArguments = new Array(); newArguments.push(name, url, {}, options); @@ -32,7 +49,7 @@ OpenLayers.Layer.TMS.prototype = }, /** - * + * APIMethod:destroy */ destroy: function() { // for now, nothing special to do here. @@ -41,10 +58,13 @@ OpenLayers.Layer.TMS.prototype = /** - * @param {Object} obj + * APIMethod: clone * - * @returns An exact clone of this OpenLayers.Layer.TMS - * @type OpenLayers.Layer.TMS + * Parameters: + * obj - {Object} + * + * Return: + * {} An exact clone of this */ clone: function (obj) { @@ -63,12 +83,15 @@ OpenLayers.Layer.TMS.prototype = }, /** - * @param {OpenLayers.Bounds} bounds + * Method: getUrl * - * @returns A string with the layer's url and parameters and also the - * passed-in bounds and appropriate tile size specified as - * parameters - * @type String + * Parameters: + * bounds - {} + * + * Return: + * {String} A string with the layer's url and parameters and also the + * passed-in bounds and appropriate tile size specified as + * parameters */ getURL: function (bounds) { bounds = this.adjustBounds(bounds); @@ -85,24 +108,28 @@ OpenLayers.Layer.TMS.prototype = }, /** - * addTile creates a tile, initializes it, and - * adds it to the layer div. - * - * @param {OpenLayers.Bounds} bounds - * - * @returns The added OpenLayers.Tile.Image - * @type OpenLayers.Tile.Image - */ + * Method: addTile + * addTile creates a tile, initializes it, and adds it to the layer div. + * + * Parameters: + * bounds - {} + * + * Return: + * {} The added OpenLayers.Tile.Image + */ addTile:function(bounds,position) { var url = this.getURL(bounds); return new OpenLayers.Tile.Image(this, position, bounds, url, this.tileSize); }, - /** When the layer is added to a map, then we can fetch our origin - * (if we don't have one.) + /** + * APIMethod: setMap + * When the layer is added to a map, then we can fetch our origin + * (if we don't have one.) * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.Grid.prototype.setMap.apply(this, arguments); @@ -112,7 +139,6 @@ OpenLayers.Layer.TMS.prototype = } }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.TMS" }); diff --git a/lib/OpenLayers/Layer/Text.js b/lib/OpenLayers/Layer/Text.js index 6b4088b966..e1a8128465 100644 --- a/lib/OpenLayers/Layer/Text.js +++ b/lib/OpenLayers/Layer/Text.js @@ -4,31 +4,45 @@ /** - * @class - * * @requires OpenLayers/Layer/Markers.js + * + * Class: OpenLayers.Layer.Text + * Tab seperated values file parsing code which creates a markers layer. + * + * Inherits from; + * - */ OpenLayers.Layer.Text = OpenLayers.Class.create(); OpenLayers.Layer.Text.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Markers, { - /** store url of text file - this should be specified in the - * "options" hashtable - * @type str */ + /** + * APIProperty: location + * {String} store url of text file - this should be specified in the + * "options" hashtable. Can not be changed once passed in. + */ location:null, - /** @type Array(OpenLayers.Feature) */ + /** + * Property: features + * Array({}) + */ features: null, - /** @type OpenLayers.Feature */ + /** + * Property: selectedFeature + * {} + */ selectedFeature: null, /** - * @constructor - * - * @param {String} name - * @param {String} location - * @param {Object} options Hashtable of extra options to tag onto the layer + * Constructor: OpenLayers.Layer.Text + * Create a text layer. + * + * Parameters: + * name - {String} + * options - {Object} Hashtable of extra options to tag onto + * the layer. Must include "location" property. */ initialize: function(name, options) { OpenLayers.Layer.Markers.prototype.initialize.apply(this, arguments); @@ -39,7 +53,7 @@ OpenLayers.Layer.Text.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { this.clearFeatures(); @@ -49,7 +63,10 @@ OpenLayers.Layer.Text.prototype = /** - * @param {XMLHttpRequest} ajaxRequest + * Method: parseData + * + * Parameters: + * ajaxRequest - {XMLHttpRequest} */ parseData: function(ajaxRequest) { var text = ajaxRequest.responseText; @@ -137,7 +154,10 @@ OpenLayers.Layer.Text.prototype = }, /** - * @param {Event} evt + * Property: markerClick + * + * Parameters: + * evt - {Event} */ markerClick: function(evt) { sameMarkerClicked = (this == this.layer.selectedFeature); @@ -152,7 +172,7 @@ OpenLayers.Layer.Text.prototype = }, /** - * + * Method: clearFeatures */ clearFeatures: function() { if (this.features != null) { diff --git a/lib/OpenLayers/Layer/Vector.js b/lib/OpenLayers/Layer/Vector.js index bf2572164d..925926c2a2 100644 --- a/lib/OpenLayers/Layer/Vector.js +++ b/lib/OpenLayers/Layer/Vector.js @@ -3,71 +3,107 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Layer.js * @requires OpenLayers/Renderer.js * @requires OpenLayers/Feature/Vector.js + * + * Class: OpenLayers.Layer.Vector + * Instances of OpenLayers.Layer.Vector are used to render vector data from + * a variety of sources. Create a new image layer with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Layer.Vector = OpenLayers.Class.create(); OpenLayers.Layer.Vector.prototype = OpenLayers.Class.inherit(OpenLayers.Layer, { - /** @type Boolean */ + /** + * APIProperty: isBaseLayer + * {Boolean} The layer is a base layer. Default is true. Set this property + * in the layer options + */ isBaseLayer: false, - /** @type Boolean */ + /** + * APIProperty: isFixed + * {Boolean} Whether the layer remains in one place while dragging the + * map. + */ isFixed: false, - /** @type Boolean */ + /** + * APIProperty: isVector + * {Boolean} Whether the layer is a vector layer. + */ isVector: true, - /** @type Array(OpenLayer.Feature.Vector) */ + /** + * APIProperty: features + * Array({}) + */ features: null, - /** @type Array(OpenLayers.Feature.Vector) */ + /** + * Property: selectedFeatures + * Array({}) + */ selectedFeatures: null, - /** @type {Boolean} */ + /** + * APIProperty: reportError + * {Boolean} report error message via alert() when loading of renderers + * fails. + */ reportError: true, - /** @type {Object} */ + /** + * APIProperty: style + * {Object} Default style for the layer + */ style: null, /** - * List of supported Renderer classes. Add to this list to + * Property: renderers + * Array({String}) List of supported Renderer classes. Add to this list to * add support for additional renderers. This list is ordered: * the first renderer which returns true for the 'supported()' * method will be used, if not defined in the 'renderer' option. - * - * @type {Array(String)} */ renderers: ['SVG', 'VML'], - /** @type OpenLayers.Renderer */ + /** + * Property: renderer + * {} + */ renderer: null, /** - * geometryType allows you to limit the types of geometries this - * layer supports. This should be set to something like + * APIProperty: geometryType + * {String} geometryType allows you to limit the types of geometries this + * layer supports. This should be set to something like * "OpenLayers.Geometry.Point" to limit types. - * - * @type string */ geometryType: null, - /** Whether the Vector Layer features have been drawn yet. - * - * @type boolean + /** + * Property: drawn + * {Boolean} Whether the Vector Layer features have been drawn yet. */ drawn: false, /** - * @constructor + * Constructor: OpenLayers.Layer.Vector + * Create a new vector layer * - * @param {String} name - * @param {Object} options Hashtable of extra options to tag onto the layer. - * Options renderer {Object}: Typically SVGRenderer or VMLRenderer. + * Parameters: + * name - {String} A name for the layer + * options - {Object} options Object with non-default properties to set on + * the layer. + * + * Return: + * {} A new vector layer */ initialize: function(name, options) { @@ -92,7 +128,8 @@ OpenLayers.Layer.Vector.prototype = }, /** - * + * APIMethod: destroy + * Destroy this layer */ destroy: function() { OpenLayers.Layer.prototype.destroy.apply(this, arguments); @@ -108,11 +145,10 @@ OpenLayers.Layer.Vector.prototype = this.drawn = null; }, - /** Iterates through the available renderer implementations and selects - * and assigns the first one whose "supported()" function returns true. - * - * @private - * + /** + * Method: assignRenderer + * Iterates through the available renderer implementations and selects + * and assigns the first one whose "supported()" function returns true. */ assignRenderer: function() { for (var i = 0; i < this.renderers.length; i++) { @@ -125,10 +161,8 @@ OpenLayers.Layer.Vector.prototype = }, /** + * Method: displayError * Let the user know their browser isn't supported. - * - * @private - * */ displayError: function() { if (this.reportError) { @@ -139,12 +173,15 @@ OpenLayers.Layer.Vector.prototype = } }, - /** The layer has been added to the map. + /** + * Method: setMap + * The layer has been added to the map. * - * If there is no renderer set, the layer can't be used. Remove it. - * Otherwise, give the renderer a reference to the map and set its size. + * If there is no renderer set, the layer can't be used. Remove it. + * Otherwise, give the renderer a reference to the map and set its size. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.prototype.setMap.apply(this, arguments); @@ -157,7 +194,9 @@ OpenLayers.Layer.Vector.prototype = } }, - /** Notify the renderer of the change in size. + /** + * Method: onMapResize + * Notify the renderer of the change in size. * */ onMapResize: function() { @@ -165,7 +204,9 @@ OpenLayers.Layer.Vector.prototype = this.renderer.setSize(this.map.getSize()); }, - /** Reset the vector layer's div so that it once again is lined up with + /** + * Method: moveTo + * Reset the vector layer's div so that it once again is lined up with * the map. Notify the renderer of the change of extent, and in the * case of a change of zoom level (resolution), have the * renderer redraw features. @@ -173,9 +214,10 @@ OpenLayers.Layer.Vector.prototype = * If the layer has not yet been drawn, cycle through the layer's * features and draw each one. * - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo: function(bounds, zoomChanged, dragging) { OpenLayers.Layer.prototype.moveTo.apply(this, arguments); @@ -197,7 +239,11 @@ OpenLayers.Layer.Vector.prototype = }, /** - * @param {Array(OpenLayers.Feature.Vector} features + * APIMethod: addFeatures + * Add Features to the layer. + * + * Parameters: + * features - {Array()} */ addFeatures: function(features) { if (!(features instanceof Array)) { @@ -235,7 +281,10 @@ OpenLayers.Layer.Vector.prototype = /** - * @param {Array(OpenLayers.Feature.Vector} features + * APIMethod: removeFeatures + * + * Parameters: + * features - {Array()} */ removeFeatures: function(features) { if (!(features instanceof Array)) { @@ -259,6 +308,7 @@ OpenLayers.Layer.Vector.prototype = }, /** + * APIMethod: destroyFeatures * Destroy all features on the layer and empty the selected features array. */ destroyFeatures: function () { @@ -269,13 +319,15 @@ OpenLayers.Layer.Vector.prototype = }, /** + * Method: drawFeature * Draw (or redraw) a feature on the layer. If the optional style argument * is included, this style will be used. If no style is included, the * feature's style will be used. If the feature doesn't have a style, * the layer's style will be used. * - * @param {OpenLayers.Feature.Vector} feature - * @param {Object} style + * Parameters: + * feature - {} + * style - {Object} */ drawFeature: function(feature, style) { if(style == null) { @@ -289,21 +341,26 @@ OpenLayers.Layer.Vector.prototype = }, /** + * Method: eraseFeatures * Erase features from the layer. - * - * @param {Array(OpenLayers.Feature.Vector)} features + * + * Parameters: + * features - {Array(OpenLayers.Feature.Vector)} */ eraseFeatures: function(features) { this.renderer.eraseFeatures(features); }, /** + * Method: getFeatureFromEvent * Given an event, return a feature if the event occurred over one. * Otherwise, return null. * - * @param {Event} - * @type OpenLayers.Feature.Vector - * @return A feature if one was under the event + * Parameters: + * evt - {Event} + * + * Returns: + * {} A feature if one was under the event. */ getFeatureFromEvent: function(evt) { var featureId = this.renderer.getFeatureIdFromEvent(evt); @@ -311,11 +368,15 @@ OpenLayers.Layer.Vector.prototype = }, /** + * APIMethod: getFeatureById * Given a feature id, return the feature if it exists in the features array - * - * @param {String} featureId - * @type OpenLayers.Feature.Vector - * @return A feature corresponding to the given featureId + * + * Parameters: + * featureId - {String} + * + * Returns: + * {} A feature corresponding to the given + * featureId */ getFeatureById: function(featureId) { //TBD - would it be more efficient to use a hash for this.features? @@ -346,26 +407,33 @@ OpenLayers.Layer.Vector.prototype = /** - * method called when a feature is inserted. + * APIMethod: onFeatureInsert + * method called after a feature is inserted. * Does nothing by default. Override this if you * need to do something on feature updates. - * - * @param {OpenLayers.Feature.Vector} feature + * + * Paarameters: + * feature - {} */ onFeatureInsert: function(feature) { }, /** + * APIMethod: preFeatureInsert * method called before a feature is inserted. * Does nothing by default. Override this if you * need to do something when features are first added to the * layer, but before they are drawn, such as adjust the style. - * - * @param {OpenLayers.Feature.Vector} feature + * + * Parameters: + * feature - {} */ preFeatureInsert: function(feature) { }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} 'OpenLayers.Layer.Vector' + */ CLASS_NAME: "OpenLayers.Layer.Vector" }); diff --git a/lib/OpenLayers/Layer/VirtualEarth.js b/lib/OpenLayers/Layer/VirtualEarth.js index 7c2069f702..73a3e7cc9c 100644 --- a/lib/OpenLayers/Layer/VirtualEarth.js +++ b/lib/OpenLayers/Layer/VirtualEarth.js @@ -4,35 +4,51 @@ /** - * @class - * * @requires OpenLayers/Layer/EventPane.js * @requires OpenLayers/Layer/FixedZoomLevels.js + * + * Class: OpenLayers.Layer.VirtualEarth + * + * Inherits: + * - + * - */ OpenLayers.Layer.VirtualEarth = OpenLayers.Class.create(); OpenLayers.Layer.VirtualEarth.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.EventPane, OpenLayers.Layer.FixedZoomLevels, { - /** @final @type int */ + /** + * Constant: MIN_ZOOM_LEVEL + * {Integer} 1 + */ MIN_ZOOM_LEVEL: 1, - /** @final @type int */ + /** + * Constant: MAX_ZOOM_LEVEL + * {Integer} 17 + */ MAX_ZOOM_LEVEL: 17, - /** Hardcode these resolutions so that they are more closely - * tied with the standard wms projection - * - * @final @type Array(float) */ + /** + * Constant: RESOLUTIONS + * {Array(Float)} Hardcode these resolutions so that they are more closely + * tied with the standard wms projection + */ RESOLUTIONS: [1.40625,0.703125,0.3515625,0.17578125,0.087890625,0.0439453125,0.02197265625,0.010986328125,0.0054931640625,0.00274658203125,0.001373291015625,0.0006866455078125,0.00034332275390625,0.000171661376953125,0.0000858306884765625,0.00004291534423828125], - /** @type VEMapType */ + /** + * APIProperty: type + * {VEMapType} + */ type: null, /** - * @constructor + * Constructor: OpenLayers.Layer.VirtualEarth * - * @param {String} name + * Parameters: + * name - {String} + * options - {Object} */ initialize: function(name, options) { OpenLayers.Layer.EventPane.prototype.initialize.apply(this, arguments); @@ -41,7 +57,7 @@ OpenLayers.Layer.VirtualEarth.prototype = }, /** - * + * Method: loadMapObject */ loadMapObject:function() { @@ -65,9 +81,11 @@ OpenLayers.Layer.VirtualEarth.prototype = }, /** - * @return String with information on why layer is broken, how to get + * APIMethod: getWarningHTML + * + * Return: + * {String} String with information on why layer is broken, how to get * it working. - * @type String */ getWarningHTML:function() { @@ -100,26 +118,33 @@ OpenLayers.Layer.VirtualEarth.prototype = // Get&Set Center, Zoom - /** Set the mapObject to the specified center and zoom + /** + * APIMethod: setMapObjectCenter + * Set the mapObject to the specified center and zoom * - * @param {Object} center MapObject LonLat format - * @param {int} zoom MapObject zoom format + * Parameters: + * center - {Object} MapObject LonLat format + * zoom - {int} MapObject zoom format */ setMapObjectCenter: function(center, zoom) { this.mapObject.SetCenterAndZoom(center, zoom); }, /** - * @returns the mapObject's current center in Map Object format - * @type Object + * APIMethod: getMapObjectCenter + * + * Return: + * {Object} The mapObject's current center in Map Object format */ getMapObjectCenter: function() { return this.mapObject.GetCenter(); }, /** - * @returns the mapObject's current zoom, in Map Object format - * @type int + * APIMethod: getMapObjectZoom + * + * Return: + * {Integer} The mapObject's current zoom, in Map Object format */ getMapObjectZoom: function() { return this.mapObject.GetZoomLevel(); @@ -128,21 +153,27 @@ OpenLayers.Layer.VirtualEarth.prototype = // LonLat - Pixel Translation - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectLonLatFromMapObjectPixel * - * @returns MapObject LonLat translated from MapObject Pixel - * @type Object + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Object} MapObject LonLat translated from MapObject Pixel */ getMapObjectLonLatFromMapObjectPixel: function(moPixel) { return this.mapObject.PixelToLatLong(moPixel.x, moPixel.y); }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectPixelFromMapObjectLonLat * - * @returns MapObject Pixel translated from MapObject LonLat - * @type Object + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Object} MapObject Pixel transtlated from MapObject LonLat */ getMapObjectPixelFromMapObjectLonLat: function(moLonLat) { return this.mapObject.LatLongToPixel(moLonLat); @@ -159,31 +190,40 @@ OpenLayers.Layer.VirtualEarth.prototype = // LonLat /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLongitudeFromMapObjectLonLat * - * @returns Longitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Longitude of the given MapObject LonLat */ getLongitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.Longitude; }, /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLatitudeFromMapObjectLonLat * - * @returns Latitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Latitude of the given MapObject LonLat */ getLatitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.Latitude; }, /** - * @param {int} lon float - * @param {int} lat float + * APIMethod: getMapObjectLonLatFromLonLat * - * @returns MapObject LonLat built from lon and lat params - * @type Object + * Parameters: + * lon - {Float} + * lat - {Float} + * + * Return: + * {Object} MapObject LonLat built from lon and lat params */ getMapObjectLonLatFromLonLat: function(lon, lat) { return new VELatLong(lat, lon); @@ -191,38 +231,46 @@ OpenLayers.Layer.VirtualEarth.prototype = // Pixel - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getXFromMapObjectPixel * - * @returns X value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} X value of the MapObject Pixel */ getXFromMapObjectPixel: function(moPixel) { return moPixel.x; }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getYFromMapObjectPixel * - * @returns Y value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} Y value of the MapObject Pixel */ getYFromMapObjectPixel: function(moPixel) { return moPixel.y; }, - /** - * @param {int} x - * @param {int} y + /** + * APIMethod: getMapObjectPixelFromXY * - * @returns MapObject Pixel from x and y parameters - * @type Object + * Parameters: + * x - {Integer} + * y - {Integer} + * + * Return: + * {Object} MapObject Pixel from x and y parameters */ - getMapObjectPixelFromXY: function(x, y) { + pObjectPixelFromXY: function(x, y) { return new Msn.VE.Pixel(x, y); }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.VirtualEarth" }); diff --git a/lib/OpenLayers/Layer/WFS.js b/lib/OpenLayers/Layer/WFS.js index bf1b52e779..c7f24b175c 100644 --- a/lib/OpenLayers/Layer/WFS.js +++ b/lib/OpenLayers/Layer/WFS.js @@ -4,55 +4,63 @@ /** - * @class - * * @requires OpenLayers/Layer/Vector.js * @requires OpenLayers/Layer/Markers.js + * + * Class: OpenLayers.Layer.WFS + * + * Inherits from: + * - + * - */ OpenLayers.Layer.WFS = OpenLayers.Class.create(); OpenLayers.Layer.WFS.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Vector, OpenLayers.Layer.Markers, { - /** WFS layer is never a base layer. - * - * @type Boolean + /** + * APIProperty: isBaseLayer + * {Boolean} WFS layer is not a base layer by default. */ isBaseLayer: false, - /** the ratio of image/tile size to map size (this is the untiled buffer) - * @type int */ + /** + * APIProperty: ratio + * {Float} the ratio of image/tile size to map size (this is the untiled + * buffer) + */ ratio: 2, - /** Hashtable of default key/value parameters - * @final @type Object */ + /** + * Property: DEFAULT_PARAMS + * {Object} Hashtable of default key/value parameters + */ DEFAULT_PARAMS: { service: "WFS", version: "1.0.0", request: "GetFeature" }, /** - * If featureClass is defined, an old-style markers based - * WFS layer is created instead of a new-style vector layer. - * If sent, this should be a subclass of OpenLayers.Feature - * - * @type OpenLayers.Feature + * APIProperty: featureClass + * {} If featureClass is defined, an old-style markers + * based WFS layer is created instead of a new-style vector layer. If + * sent, this should be a subclass of OpenLayers.Feature */ featureClass: null, /** - * Should be calculated automatically. - * - * @type Boolean + * Property: vectorMode + * {Boolean} Should be calculated automatically. */ vectorMode: true, /** - * @constructor + * Constructor: OpenLayers.Layer.WFS * - * @param {String} name - * @param {String} url - * @param {Object} params - * @param {Object} options Hashtable of extra options to tag onto the layer + * Parameters: + * name - {String} + * url - {String} + * params - {Object} + * options - {Object} Hashtable of extra options to tag onto the layer */ initialize: function(name, url, params, options) { if (options == undefined) { options = {}; } @@ -93,7 +101,7 @@ OpenLayers.Layer.WFS.prototype = /** - * + * APIMethod: destroy */ destroy: function() { if (this.vectorMode) { @@ -104,7 +112,10 @@ OpenLayers.Layer.WFS.prototype = }, /** - * @param {OpenLayers.Map} map + * Method: setMap + * + * Parameters: + * map - {} */ setMap: function(map) { if (this.vectorMode) { @@ -115,9 +126,12 @@ OpenLayers.Layer.WFS.prototype = }, /** - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * Method: moveTo + * + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { if (this.vectorMode) { @@ -204,6 +218,7 @@ OpenLayers.Layer.WFS.prototype = }, /** + * Method: onMapResize * Call the onMapResize method of the appropriate parent class. */ onMapResize: function() { @@ -215,10 +230,13 @@ OpenLayers.Layer.WFS.prototype = }, /** - * @param {Object} obj + * APIMethod: clone + * + * Parameters: + * obj - {Object} * - * @returns An exact clone of this OpenLayers.Layer.WMS - * @type OpenLayers.Layer.WMS + * Returns: + * {} LAn exact clone of this OpenLayers.Layer.WFS */ clone: function (obj) { @@ -241,16 +259,17 @@ OpenLayers.Layer.WFS.prototype = return obj; }, - /** combine the layer's url with its params and these newParams. - * - * Add the SRS parameter from 'projection' -- this is probably - * more eloquently done via a setProjection() method, but this - * works for now and always. - * - * @param {Object} newParams - * - * @type String - */ + /** + * APIMethod: getFullRequestString + * combine the layer's url with its params and these newParams. + * + * Add the SRS parameter from 'projection' -- this is probably + * more eloquently done via a setProjection() method, but this + * works for now and always. + * + * Parameters: + * newParams - {Object} + */ getFullRequestString:function(newParams) { var projection = this.map.getProjection(); this.params.SRS = (projection == "none") ? null : projection; @@ -258,7 +277,11 @@ OpenLayers.Layer.WFS.prototype = return OpenLayers.Layer.Grid.prototype.getFullRequestString.apply( this, arguments); }, - + + /** + * APIMethod: commit + * Write out the data to a WFS server. + */ commit: function() { if (!this.writer) { this.writer = new OpenLayers.Format.WFS({},this); @@ -288,9 +311,11 @@ OpenLayers.Layer.WFS.prototype = }, /** + * Method: commitSuccess * Called when the Ajax request returns a response * - * @param {XmlNode} response from server + * Parameters: + * response - {XmlNode} from server */ commitSuccess: function(request) { var response = request.responseText; @@ -309,18 +334,22 @@ OpenLayers.Layer.WFS.prototype = }, /** + * Method: commitFailure * Called when the Ajax request fails * - * @param {XmlNode} response from server + * Parameters: + * response - {XmlNode} from server */ commitFailure: function(request) {}, /** + * APIMethod: commitReport * Called with a 'success' message if the commit succeeded, otherwise - * a failure message, and the full text as a second parameter. + * a failure message, and the full request text as a second parameter. + * Override this function to provide custom transaction reporting. * - * @param {String} string reporting string - * @param {String} response full XML response + * string - {String} reporting string + * response - {String} full XML response */ commitReport: function(string, response) { alert(string); @@ -328,6 +357,7 @@ OpenLayers.Layer.WFS.prototype = /** + * APIMethod: refresh * Refreshes all the features of the layer */ refresh: function() { diff --git a/lib/OpenLayers/Layer/WMS.js b/lib/OpenLayers/Layer/WMS.js index 8e0407b57c..5bacc2764d 100644 --- a/lib/OpenLayers/Layer/WMS.js +++ b/lib/OpenLayers/Layer/WMS.js @@ -4,17 +4,25 @@ /** - * @class - * * @requires OpenLayers/Layer/Grid.js * @requires OpenLayers/Tile/Image.js + * + * Class: OpenLayers.Layer.WMS + * Instances of OpenLayers.Layer.WMS are used to display data from OGC Web + * Mapping Services. Create a new WMS layer with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Layer.WMS = OpenLayers.Class.create(); OpenLayers.Layer.WMS.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.Grid, { - /** Hashtable of default parameter key/value pairs - * @final @type Object */ + /** + * Constant: DEFAULT_PARAMS + * {Object} Hashtable of default parameter key/value pairs + */ DEFAULT_PARAMS: { service: "WMS", version: "1.1.1", request: "GetMap", @@ -23,16 +31,34 @@ OpenLayers.Layer.WMS.prototype = format: "image/jpeg" }, + /** + * Property: reproject + * {Boolean} Try to reproject this layer if its coordinate reference system + * is different than that of the base layer. Default is true. + * Set this in the layer options. Should be set to false in + * most cases. + */ reproject: true, /** - * @constructor - * - * @param {String} name - * @param {String} url - * @param {Object} params - * @param {Object} options Hashtable of extra options to tag onto the layer - */ + * Constructor: OpenLayers.Layer.WMS + * Create a new WMS layer object + * + * Example: + * (code) + * var wms = new OpenLayers.Layer.WMS("NASA Global Mosaic", + * "http://wms.jpl.nasa.gov/wms.cgi", + * {layers: "modis,global_mosaic"}); + * (end) + * + * Parameters: + * name - {String} A name for the layer + * url - {String} Base url for the WMS + * (e.g. http://wms.jpl.nasa.gov/wms.cgi) + * params - {Object} An object with key/value pairs representing the + * GetMap query string parameters and parameter values. + * options - {Ojbect} Hashtable of extra options to tag onto the layer + */ initialize: function(name, url, params, options) { var newArguments = new Array(); //uppercase params @@ -54,7 +80,8 @@ OpenLayers.Layer.WMS.prototype = }, /** - * + * Method: destroy + * Destroy this layer */ destroy: function() { // for now, nothing special to do here. @@ -63,10 +90,11 @@ OpenLayers.Layer.WMS.prototype = /** - * @param {Object} obj - * - * @returns An exact clone of this OpenLayers.Layer.WMS - * @type OpenLayers.Layer.WMS + * Method: clone + * Create a clone of this layer + * + * Return: + * {} An exact clone of this layer */ clone: function (obj) { @@ -86,12 +114,17 @@ OpenLayers.Layer.WMS.prototype = }, /** - * @param {OpenLayers.Bounds} bounds - * - * @returns A string with the layer's url and parameters and also the - * passed-in bounds and appropriate tile size specified as - * parameters - * @type String + * Method: getURL + * Return a GetMap query string for this layer + * + * Parameters: + * bounds - {} A bounds representing the bbox for the + * request. + * + * Return: + * {String} A string with the layer's url and parameters and also the + * passed-in bounds and appropriate tile size specified as + * parameters. */ getURL: function (bounds) { bounds = this.adjustBounds(bounds); @@ -102,14 +135,15 @@ OpenLayers.Layer.WMS.prototype = }, /** - * addTile creates a tile, initializes it, and - * adds it to the layer div. - * - * @param {OpenLayers.Bounds} bounds - * - * @returns The added OpenLayers.Tile.Image - * @type OpenLayers.Tile.Image - */ + * Method: addTile + * addTile creates a tile, initializes it, and adds it to the layer div. + * + * Parameters: + * bounds - {} + * + * Return: + * {} The added OpenLayers.Tile.Image + */ addTile:function(bounds,position) { var url = this.getURL(bounds); return new OpenLayers.Tile.Image(this, position, bounds, @@ -117,12 +151,14 @@ OpenLayers.Layer.WMS.prototype = }, /** + * APIMethod: mergeNewParams * Catch changeParams and uppercase the new params to be merged in - * before calling changeParams on the super class. + * before calling changeParams on the super class. * - * Once params have been changed, we will need to re-init our tiles + * Once params have been changed, we will need to re-init our tiles. * - * @param {Object} newParams Hashtable of new params to use + * Parameters: + * newParams - {Object} Hashtable of new params to use */ mergeNewParams:function(newParams) { var upperParams = OpenLayers.Util.upperCaseObject(newParams); @@ -131,16 +167,20 @@ OpenLayers.Layer.WMS.prototype = newArguments); }, - /** combine the layer's url with its params and these newParams. - * - * Add the SRS parameter from projection -- this is probably - * more eloquently done via a setProjection() method, but this - * works for now and always. - * - * @param {Object} newParams - * - * @type String - */ + /** + * Method: getFullRequestString + * Combine the layer's url with its params and these newParams. + * + * Add the SRS parameter from projection -- this is probably + * more eloquently done via a setProjection() method, but this + * works for now and always. + * + * Parameters: + * newParams - {Object} + * + * Return: + * {String} + */ getFullRequestString:function(newParams) { var projection = this.map.getProjection(); this.params.SRS = (projection == "none") ? null : projection; diff --git a/lib/OpenLayers/Layer/WMS/Untiled.js b/lib/OpenLayers/Layer/WMS/Untiled.js index 2223083b25..acb8357844 100644 --- a/lib/OpenLayers/Layer/WMS/Untiled.js +++ b/lib/OpenLayers/Layer/WMS/Untiled.js @@ -4,17 +4,22 @@ /** - * @class - * * @requires OpenLayers/Layer/HTTPRequest.js * @requires OpenLayers/Layer/WMS.js + * + * Class: OpenLayers.Layer.WMS + * + * Inherits from: + * - */ OpenLayers.Layer.WMS.Untiled = OpenLayers.Class.create(); OpenLayers.Layer.WMS.Untiled.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.HTTPRequest, { - /** Hashtable of default parameter key/value pairs - * @final @type Object */ + /** + * Property: DEFAULT_PARAMS + * Hashtable of default parameter key/value pairs + */ DEFAULT_PARAMS: { service: "WMS", version: "1.1.1", request: "GetMap", @@ -22,25 +27,40 @@ OpenLayers.Layer.WMS.Untiled.prototype = exceptions: "application/vnd.ogc.se_inimage", format: "image/jpeg" }, + /** + * APIProperty: reproject + * Whether or not to use the base layer as a basis for 'staking' the corners + * of the image geographically. + */ reproject: true, - /** the ratio of image/tile size to map size (this is the untiled buffer) - * @type int */ + /** + * APIProperty: ratio + * {Float} the ratio of image/tile size to map size (this is the untiled + * buffer) + */ ratio: 2, - /** @type OpenLayers.Tile.Image */ + /** + * Property: tile + * {} + */ tile: null, - /** did the image finish loading before a new draw was initiated? - * @type Boolean */ + /** + * Property: doneLoading + * {Boolean} did the image finish loading before a new draw was initiated? + */ doneLoading: false, /** - * @constructor + * Constructor: OpenLayers.Layer.WMS.Untiled * - * @param {String} name - * @param {String} url - * @param {Object} params + * Parameters: + * name - {String} + * url - {String} + * params - {Object} + * options - {Object} */ initialize: function(name, url, params, options) { var newArguments = new Array(); @@ -64,7 +84,7 @@ OpenLayers.Layer.WMS.Untiled.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { if (this.tile) { @@ -75,10 +95,14 @@ OpenLayers.Layer.WMS.Untiled.prototype = }, /** - * @param {Object} obj + * APIMethod: clone + * Makes an exact clone of this OpenLayers.Layer.WMS.Untiled * - * @returns An exact clone of this OpenLayers.Layer.WMS.Untiled - * @type OpenLayers.Layer.WMS.Untiled + * Parameters: + * obj - {Object} + * + * Returns: + * {} */ clone: function (obj) { @@ -100,15 +124,19 @@ OpenLayers.Layer.WMS.Untiled.prototype = }, - /** Once HTTPRequest has set the map, we can load the image div + /** + * Method: setMap + * Once HTTPRequest has set the map, we can load the image div * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.HTTPRequest.prototype.setMap.apply(this, arguments); }, /** + * Method: setTileSize * Set the tile size based on the map size. This also sets layer.imageSize * and layer.imageOffset for use by Tile.Image. */ @@ -121,12 +149,15 @@ OpenLayers.Layer.WMS.Untiled.prototype = this.imageOffset = new OpenLayers.Pixel(0, 0); }, - /** When it is not a dragging move (ie when done dragging) + /** + * Method: moveTo + * When it is not a dragging move (ie when done dragging) * reload and recenter the div. * - * @param {OpenLayers.Bounds} bounds - * @param {Boolean} zoomChanged - * @param {Boolean} dragging + * Parameters: + * bounds - {} + * zoomChanged - {Boolean} + * dragging - {Boolean} */ moveTo:function(bounds, zoomChanged, dragging) { if (!this.doneLoading) { @@ -197,6 +228,12 @@ OpenLayers.Layer.WMS.Untiled.prototype = } }, + /** + * Method: getURL + * + * Parameters: + * bounds - {} + */ getURL: function(bounds) { return this.getFullRequestString( {'BBOX': bounds.toBBOX(), 'WIDTH': this.tileSize.w, @@ -204,16 +241,24 @@ OpenLayers.Layer.WMS.Untiled.prototype = }, - /** Once HTTPRequest has updated the url, reload the image div - * @param {String} newUrl + /** + * Method: setURL + * Once HTTPRequest has updated the url, reload the image div + * + * Parameters: + * newUrl - {String} */ setUrl: function(newUrl) { OpenLayers.Layer.HTTPRequest.prototype.setUrl.apply(this, arguments); this.moveTo(); }, - /** Once HTTPRequest has updated new params, reload the image div - * @param {Object} newParams + /** + * APIMethod: mergeNewParams + * Once HTTPRequest has updated new params, reload the image div + * + * Parameters: + * newParams - {Object} */ mergeNewParams:function(newParams) { var upperParams = OpenLayers.Util.upperCaseObject(newParams); @@ -224,15 +269,16 @@ OpenLayers.Layer.WMS.Untiled.prototype = this.moveTo(null, true); }, - /** combine the layer's url with its params and these newParams. + /** + * APIMethod: getFullRequestString + * combine the layer's url with its params and these newParams. * * Add the SRS parameter from 'projection' -- this is probably * more eloquently done via a setProjection() method, but this * works for now and always. * - * @param {Object} newParams - * - * @type String + * Parameters: + * newParams - {Object} */ getFullRequestString:function(newParams) { var projection = this.map.getProjection(); diff --git a/lib/OpenLayers/Layer/WorldWind.js b/lib/OpenLayers/Layer/WorldWind.js index dee1784cfd..fe5bfcfaf2 100644 --- a/lib/OpenLayers/Layer/WorldWind.js +++ b/lib/OpenLayers/Layer/WorldWind.js @@ -4,9 +4,12 @@ /** - * @class - * * @requires OpenLayers/Layer/Grid.js + * + * Class: OpenLayers.Layer.WorldWind + * + * Inherits from: + * - */ OpenLayers.Layer.WorldWind = OpenLayers.Class.create(); OpenLayers.Layer.WorldWind.prototype = @@ -15,17 +18,36 @@ OpenLayers.Layer.WorldWind.prototype = DEFAULT_PARAMS: { }, - /** WorldWind layer is always a base layer - * - * @type Boolean + /** + * APIProperty: isBaseLayer + * WorldWind layer is a base layer by default. */ isBaseLayer: true, - // LevelZeroTileSizeDegrees + + /** + * APIProperty: lzd + * LevelZeroTileSizeDegrees + */ lzd: null, + /** + * APIProperty: zoomLevels + * Number of zoom levels. + */ zoomLevels: null, - + + /** + * Constructor: OpenLayers.Layer.WorldWind + * + * Parameters: + * name - {String} Name of Layer + * url - {String} Base URL + * lzd - {Float} Level zero tile size degrees + * zoomLevels - {Int} number of zoom levels + * params - {Object} additional parameters + * options - {Object} additional options + */ initialize: function(name, url, lzd, zoomLevels, params, options) { this.lzd = lzd; this.zoomLevels = zoomLevels; @@ -40,6 +62,9 @@ OpenLayers.Layer.WorldWind.prototype = ); } }, + /** + * Method: addTile + */ addTile:function(bounds,position) { if (this.map.getResolution() <= (this.lzd/512) && this.getZoom() <= this.zoomLevels) { @@ -53,6 +78,10 @@ OpenLayers.Layer.WorldWind.prototype = } }, + /** + * Method: getZoom + * Convert map zoom to WW zoom. + */ getZoom: function () { var zoom = this.map.getZoom(); var extent = this.map.getMaxExtent(); @@ -61,12 +90,15 @@ OpenLayers.Layer.WorldWind.prototype = }, /** - * @param {OpenLayers.Bounds} bounds - * - * @returns A string with the layer's url and parameters and also the + * Method: getURL + * + * Parameters: + * bounds - {} + * + * Returns: + * {String} A string with the layer's url and parameters and also the * passed-in bounds and appropriate tile size specified as * parameters - * @type String */ getURL: function (bounds) { bounds = this.adjustBounds(bounds); diff --git a/lib/OpenLayers/Layer/Yahoo.js b/lib/OpenLayers/Layer/Yahoo.js index ed93b5b0c7..2ad3e591a3 100644 --- a/lib/OpenLayers/Layer/Yahoo.js +++ b/lib/OpenLayers/Layer/Yahoo.js @@ -4,35 +4,51 @@ /** - * @class - * * @requires OpenLayers/Layer/EventPane.js * @requires OpenLayers/Layer/FixedZoomLevels.js + * + * Class: OpenLayers.Layer.Yahoo + * + * Inherits: + * - + * - v */ OpenLayers.Layer.Yahoo = OpenLayers.Class.create(); OpenLayers.Layer.Yahoo.prototype = OpenLayers.Class.inherit( OpenLayers.Layer.EventPane, OpenLayers.Layer.FixedZoomLevels, { - /** @final @type int */ + /** + * Constant: MIN_ZOOM_LEVEL + * {Integer} 0 + */ MIN_ZOOM_LEVEL: 0, - /** @final @type int */ + /** + * Constant: MAX_ZOOM_LEVEL + * {Integer} 15 + */ MAX_ZOOM_LEVEL: 15, - /** Hardcode these resolutions so that they are more closely - * tied with the standard wms projection - * - * @final @type Array(float) */ + /** + * Constant: RESOLUTIONS + * {Array(Float)} Hardcode these resolutions so that they are more closely + * tied with the standard wms projection + */ RESOLUTIONS: [1.40625,0.703125,0.3515625,0.17578125,0.087890625,0.0439453125,0.02197265625,0.010986328125,0.0054931640625,0.00274658203125,0.001373291015625,0.0006866455078125,0.00034332275390625,0.000171661376953125,0.0000858306884765625,0.00004291534423828125], - /** @type YahooMapType */ + /** + * APIProperty: type + * {YahooMapType} + */ type: null, /** - * @constructor + * Constructor: OpenLayers.Layer.Yahoo * - * @param {String} name + * Parameters: + * name - {String} + * options - {Object} */ initialize: function(name, options) { OpenLayers.Layer.EventPane.prototype.initialize.apply(this, arguments); @@ -41,7 +57,7 @@ OpenLayers.Layer.Yahoo.prototype = }, /** - * + * Method: loadMapObject */ loadMapObject:function() { try { //do not crash! @@ -50,11 +66,14 @@ OpenLayers.Layer.Yahoo.prototype = }, - /** Overridden from EventPane because we need to remove this yahoo event - * pane which prohibits our drag and drop, and we can only do this - * once the map has been loaded and centered. + /** + * APIMethod: setMap + * Overridden from EventPane because we need to remove this yahoo event + * pane which prohibits our drag and drop, and we can only do this + * once the map has been loaded and centered. * - * @param {OpenLayers.Map} map + * Parameters: + * map - {} */ setMap: function(map) { OpenLayers.Layer.EventPane.prototype.setMap.apply(this, arguments); @@ -62,10 +81,10 @@ OpenLayers.Layer.Yahoo.prototype = this.map.events.register("moveend", this, this.fixYahooEventPane); }, - /** The map has been centered, so the mysterious yahoo eventpane has been - * added. we remove it so that it doesnt mess with *our* event pane. - * - * @private + /** + * Method: fixYahooEventPane + * The map has been centered, so the mysterious yahoo eventpane has been + * added. we remove it so that it doesnt mess with *our* event pane. */ fixYahooEventPane: function() { var yahooEventPane = OpenLayers.Util.getElement("ygddfdiv"); @@ -79,9 +98,11 @@ OpenLayers.Layer.Yahoo.prototype = }, /** - * @return String with information on why layer is broken, how to get + * APIMethod: getWarningHTML + * + * Return: + * {String} String with information on why layer is broken, how to get * it working. - * @type String */ getWarningHTML:function() { @@ -118,11 +139,14 @@ OpenLayers.Layer.Yahoo.prototype = // /** - * @param {int} gZoom + * APIMethod: getOLZoomFromMapObjectZoom * - * @returns An OpenLayers Zoom level, translated from the passed in gZoom - * Returns null if null value is passed in - * @type int + * Parameters: + * gZoom - {Integer} + * + * Return: + * {Integer} An OpenLayers Zoom level, translated from the passed in gZoom + * Returns null if null value is passed in. */ getOLZoomFromMapObjectZoom: function(moZoom) { var zoom = null; @@ -134,11 +158,14 @@ OpenLayers.Layer.Yahoo.prototype = }, /** - * @param {int} olZoom + * APIMethod: getMapObjectZoomFromOLZoom * - * @returns A MapObject level, translated from the passed in olZoom - * Returns null if null value is passed in - * @type int + * Parameters: + * olZoom - {Integer} + * + * Return: + * {Integer} A MapObject level, translated from the passed in olZoom + * Returns null if null value is passed in */ getMapObjectZoomFromOLZoom: function(olZoom) { var zoom = null; @@ -158,26 +185,33 @@ OpenLayers.Layer.Yahoo.prototype = // Get&Set Center, Zoom - /** Set the mapObject to the specified center and zoom + /** + * APIMethod: setMapObjectCenter + * Set the mapObject to the specified center and zoom * - * @param {Object} center MapObject LonLat format - * @param {int} zoom MapObject zoom format + * Parameters: + * center - {Object} MapObject LonLat format + * zoom - {int} MapObject zoom format */ setMapObjectCenter: function(center, zoom) { this.mapObject.drawZoomAndCenter(center, zoom); }, /** - * @returns the mapObject's current center in Map Object format - * @type Object + * APIMethod: getMapObjectCenter + * + * Return: + * {Object} The mapObject's current center in Map Object format */ getMapObjectCenter: function() { return this.mapObject.getCenterLatLon(); }, /** - * @returns the mapObject's current zoom, in Map Object format - * @type int + * APIMethod: getMapObjectZoom + * + * Return: + * {Integer} The mapObject's current zoom, in Map Object format */ getMapObjectZoom: function() { return this.mapObject.getZoomLevel(); @@ -186,21 +220,27 @@ OpenLayers.Layer.Yahoo.prototype = // LonLat - Pixel Translation - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectLonLatFromMapObjectPixel * - * @returns MapObject LonLat translated from MapObject Pixel - * @type Object + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Object} MapObject LonLat translated from MapObject Pixel */ getMapObjectLonLatFromMapObjectPixel: function(moPixel) { return this.mapObject.convertXYLatLon(moPixel); }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getMapObjectPixelFromMapObjectLonLat * - * @returns MapObject Pixel translated from MapObject LonLat - * @type Object + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Object} MapObject Pixel transtlated from MapObject LonLat */ getMapObjectPixelFromMapObjectLonLat: function(moLonLat) { return this.mapObject.convertLatLonXY(moLonLat); @@ -217,31 +257,40 @@ OpenLayers.Layer.Yahoo.prototype = // LonLat /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLongitudeFromMapObjectLonLat * - * @returns Longitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Longitude of the given MapObject LonLat */ getLongitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.Lon; }, /** - * @param {Object} moLonLat MapObject LonLat format + * APIMethod: getLatitudeFromMapObjectLonLat * - * @returns Latitude of the given MapObject LonLat - * @type float + * Parameters: + * moLonLat - {Object} MapObject LonLat format + * + * Return: + * {Float} Latitude of the given MapObject LonLat */ getLatitudeFromMapObjectLonLat: function(moLonLat) { return moLonLat.Lat; }, /** - * @param {int} lon float - * @param {int} lat float + * APIMethod: getMapObjectLonLatFromLonLat * - * @returns MapObject LonLat built from lon and lat params - * @type Object + * Parameters: + * lon - {Float} + * lat - {Float} + * + * Return: + * {Object} MapObject LonLat built from lon and lat params */ getMapObjectLonLatFromLonLat: function(lon, lat) { return new YGeoPoint(lat, lon); @@ -249,38 +298,46 @@ OpenLayers.Layer.Yahoo.prototype = // Pixel - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getXFromMapObjectPixel * - * @returns X value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} X value of the MapObject Pixel */ getXFromMapObjectPixel: function(moPixel) { return moPixel.x; }, - /** - * @param {Object} moPixel MapObject Pixel format + /** + * APIMethod: getYFromMapObjectPixel * - * @returns Y value of the MapObject Pixel - * @type int + * Parameters: + * moPixel - {Object} MapObject Pixel format + * + * Return: + * {Integer} Y value of the MapObject Pixel */ getYFromMapObjectPixel: function(moPixel) { return moPixel.y; }, - /** - * @param {int} x - * @param {int} y + /** + * APIMethod: getMapObjectPixelFromXY * - * @returns MapObject Pixel from x and y parameters - * @type Object + * Parameters: + * x - {Integer} + * y - {Integer} + * + * Return: + * {Object} MapObject Pixel from x and y parameters */ getMapObjectPixelFromXY: function(x, y) { return new YCoordPoint(x, y); }, - /** @final @type String */ CLASS_NAME: "OpenLayers.Layer.Yahoo" }); diff --git a/lib/OpenLayers/Map.js b/lib/OpenLayers/Map.js index 7446290b7a..6f2c70dbcc 100644 --- a/lib/OpenLayers/Map.js +++ b/lib/OpenLayers/Map.js @@ -4,25 +4,36 @@ /** - * @class - * * @requires OpenLayers/Util.js * @requires OpenLayers/Events.js + * + * Class: OpenLayers.Map + * Instances of OpenLayers.Map are interactive maps embedded in a web page. + * Create a new map with the constructor. */ OpenLayers.Map = OpenLayers.Class.create(); +/** + * Constant: TILE_WIDTH + * {Integer} 256 Default tile width (unless otherwise specified) + */ OpenLayers.Map.TILE_WIDTH = 256; +/** + * Constant: TILE_HEIGHT + * {Integer} 256 Default tile height (unless otherwise specified) + */ OpenLayers.Map.TILE_HEIGHT = 256; OpenLayers.Map.prototype = { - /** base z-indexes for different classes of thing - * - * @type Object + /** + * Constant: Z_INDEX_BASE + * {Object} Base z-indexes for different classes of thing */ Z_INDEX_BASE: { BaseLayer: 100, Overlay: 325, Popup: 750, Control: 1000 }, - /** supported application event types - * - * @type Array */ + /** + * Constant: EVENT_TYPES + * {Array} supported application event types + */ EVENT_TYPES: [ "addlayer", "removelayer", "changelayer", "movestart", "move", "moveend", "zoomend", "popupopen", "popupclose", @@ -30,127 +41,215 @@ OpenLayers.Map.prototype = { "mouseout", "mousemove", "dragstart", "drag", "dragend", "changebaselayer"], - /** @type String */ + /** + * Property: id + * {String} Unique identifier for the map + */ id: null, - /** @type OpenLayers.Events */ + /** + * APIProperty: events + * {} An events object that handles all + * events on the map + */ events: null, - /** function that is called to destroy the map on page unload. stored - * here so that if map is manually destroyed, we can unregister this. - * - * @type Function */ - unloadDestroy: null, - - /** the div that our map lives in - * - * @type DOMElement */ + /** + * APIProperty: div + * {DOMElement} The element that contains the map + */ div: null, - /** Size of the main div (this.div) - * - * @type OpenLayers.Size */ + /** + * Property: size + * {} Size of the main div (this.div) + */ size: null, - /** @type HTMLDivElement */ + /** + * Property: viewPortDiv + * {HTMLDivElement} The element that represents the map viewport + */ viewPortDiv: null, - /** The lonlat at which the later container was re-initialized (on-zoom) - * @type OpenLayers.LonLat */ + /** + * Property: layerContainerOrigin + * {} The lonlat at which the later container was + * re-initialized (on-zoom) + */ layerContainerOrigin: null, - /** @type HTMLDivElement */ + /** + * Property: layerContainerDiv + * {HTMLDivElement} The element that contains the layers. + */ layerContainerDiv: null, - /** ordered list of layers in the map - * - * @type Array(OpenLayers.Layer) + /** + * Property: layers + * {Array()} Ordered list of layers in the map */ layers: null, - /** @type Array(OpenLayers.Control) */ + /** + * Property: controls + * {Array()} List of controls associated with the map + */ controls: null, - /** @type Array(OpenLayers.Popup) */ + /** + * Property: popups + * {Array()} List of popups associated with the map + */ popups: null, - /** The currently selected base layer - this determines min/max zoom level, - * projection, etc. - * - * @type OpenLayers.Layer */ + /** + * APIProperty: baseLayer + * {} The currently selected base layer - this determines + * min/max zoom level, projection, etc. + */ baseLayer: null, - /** @type OpenLayers.LonLat */ + /** + * Property: center + * {} The current center of the map + */ center: null, - /** @type int */ + /** + * Property: zoom + * {Integer} The current zoom level of the map + */ zoom: 0, - /** Used to store a unique identifier that changes when the map view - * changes. viewRequestID should be used when adding data asynchronously - * to the map: viewRequestID is incremented when you initiate your - * request (right now during changing of baselayers and changing of zooms). - * It is stored here in the map and also in the data that will be coming - * back asynchronously. Before displaying this data on request completion, - * we check that the viewRequestID of the data is still the same as that - * of the map. Fix for #480 - * - * @type String */ + /** + * Property: viewRequestID + * {String} Used to store a unique identifier that changes when the map + * view changes. viewRequestID should be used when adding data + * asynchronously to the map: viewRequestID is incremented when + * you initiate your request (right now during changing of + * baselayers and changing of zooms). It is stored here in the + * map and also in the data that will be coming back + * asynchronously. Before displaying this data on request + * completion, we check that the viewRequestID of the data is + * still the same as that of the map. Fix for #480 + */ viewRequestID: 0, - // Options + // Options - /** @type OpenLayers.Size */ + /** + * APIProperty: tileSize + * {} Set in the map options to override the default tile + * size for this map. + */ tileSize: null, - /** @type String */ + /** + * Property: projection + * {String} Set in the map options to override the default projection + * string this map - also set maxExtent, maxResolution, and + * units if appropriate. + */ projection: "EPSG:4326", - /** @type String */ + /** + * Property: units + * {String} The map units. Defaults to 'degrees'. Possible values are + * 'degrees' (or 'dd'), 'm', 'ft', 'km', 'mi', 'inches'. + */ units: 'degrees', - /** default max is 360 deg / 256 px, which corresponds to - * zoom level 0 on gmaps - * - * @type float */ + /** + * Property: maxResolution + * {Float} Default max is 360 deg / 256 px, which corresponds to + * zoom level 0 on gmaps. Specify a different value in the map + * options if you are not using a geographic projection and + * displaying the whole world. + */ maxResolution: 1.40625, - /** @type float */ + /** + * Property: minResolution + * {Float} + */ minResolution: null, - /** @type float */ + /** + * Property: maxScale + * {Float} + */ maxScale: null, - /** @type float */ + /** + * Property: minScale + * {Float} + */ minScale: null, - /** @type OpenLayers.Bounds */ + /** + * Property: maxExtent + * {} The maximum extent for the map. Defaults to the + * whole world in decimal degrees + * (-180, -90, 180, 90). Specify a different + * extent in the map options if you are not using a + * geographic projection and displaying the whole + * world. + */ maxExtent: null, - /** @type OpenLayers.Bounds */ + /** + * Property: minExtent + * {} + */ minExtent: null, - /** @type int */ + /** + * Property: numZoomLevels + * {Integer} Number of zoom levels for the map. Defaults to 16. Set a + * different value in the map options if needed. + */ numZoomLevels: 16, - /** A pointer to a CSS file from which to load theme styles - * @type string */ + /** + * APIProperty: theme + * {String} Relative path to a CSS file from which to load theme styles. + * Specify null in the map options (e.g. {theme: null}) if you + * want to get cascading style declarations - by putting links to + * stylesheets or style declarations directly in your page. + */ theme: null, - /** Should OpenLayers allow events on the map to fall through to other - * elements on the page, or should it swallow them? (#457) - * - * Default is to swallow them. - * - * @type boolean + /** + * APIProperty: fallThrough + * {Boolean} Should OpenLayers allow events on the map to fall through to + * other elements on the page, or should it swallow them? (#457) + * Default is to swallow them. */ fallThrough: false, /** - * @constructor - * - * @param {DOMElement} div - * @param {Object} options Hashtable of extra options to tag onto the map + * Constructor: OpenLayers.Map + * Constructor for a new OpenLayers.Map instance. + * + * Parameters: + * div - {String} Id of an element in your page that will contain the map. + * options - {Object} Optional object with properties to tag onto the map. + * + * Examples: + * (code) + * // create a map with default options in an element with the id "map1" + * var map = new OpenLayers.Map("map1"); + * + * // create a map with non-default options in an element with id "map2" + * var options = { + * maxExtent: new OpenLayers.Bounds(-200000, -200000, 200000, 200000), + * maxResolution: 156543, + * units: 'meters', + * projection: "EPSG:41001" + * }; + * var map = new OpenLayers.Map("map2", options); + * (end) */ initialize: function (div, options) { @@ -179,14 +278,17 @@ OpenLayers.Map.prototype = { this.viewPortDiv.appendChild(this.layerContainerDiv); - this.events = new OpenLayers.Events(this, div, this.EVENT_TYPES, this.fallThrough); + this.events = new OpenLayers.Events(this, + div, + this.EVENT_TYPES, + this.fallThrough); this.updateSize(); // update the map size and location before the map moves this.events.register("movestart", this, this.updateSize); - // Because Mozilla does not support the "resize" event for elements other - // than "window", we need to put a hack here. + // Because Mozilla does not support the "resize" event for elements + // other than "window", we need to put a hack here. if (navigator.appName.contains("Microsoft")) { // If IE, register the resize on the div this.events.register("resize", this, this.updateSize); @@ -249,8 +351,16 @@ OpenLayers.Map.prototype = { }, /** - * @private - */ + * Method: unloadDestroy + * Function that is called to destroy the map on page unload. stored here + * so that if map is manually destroyed, we can unregister this. + */ + unloadDestroy: null, + + /** + * APIMethod: destroy + * Destroy this map + */ destroy:function() { // if unloadDestroy is null, we've already been destroyed if (!this.unloadDestroy) { @@ -286,9 +396,11 @@ OpenLayers.Map.prototype = { }, /** - * @private - * - * @param {Object} options Hashtable of options to tag to the map + * APIMethod: setOptions + * Change the map options + * + * Parameters: + * options - {Object} Hashtable of options to tag to the map */ setOptions: function(options) { @@ -308,7 +420,11 @@ OpenLayers.Map.prototype = { }, /** - * @type OpenLayers.Size + * APIMethod: getTileSize + * Get the tile size for the map + * + * Return: + * {} */ getTileSize: function() { return this.tileSize; @@ -324,11 +440,15 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @param {String} name - * - * @returns The Layer with the corresponding id from the map's - * layer collection, or null if not found. - * @type OpenLayers.Layer + * APIMethod: getLayer + * Get a layer based on its id + * + * Parameter: + * id - {String} A layer id + * + * Return: + * {} The Layer with the corresponding id from the map's + * layer collection, or null if not found. */ getLayer: function(id) { var foundLayer = null; @@ -342,9 +462,11 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.Layer} layer - * @param {int} zIdx - * @private + * Method: setLayerZIndex + * + * Parameters: + * layer - {} + * zIdx - {int} */ setLayerZIndex: function (layer, zIdx) { layer.setZIndex( @@ -353,7 +475,10 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.Layer} layer + * APIMethod: addLayer + * + * Parameters: + * layer - {} */ addLayer: function (layer) { for(var i=0; i < this.layers.length; i++) { @@ -390,7 +515,10 @@ OpenLayers.Map.prototype = { }, /** - * @param {Array(OpenLayers.Layer)} layers + * APIMethod: addLayers + * + * Parameters: + * layers - Array({}) */ addLayers: function (layers) { for (var i = 0; i < layers.length; i++) { @@ -398,7 +526,9 @@ OpenLayers.Map.prototype = { } }, - /** Removes a layer from the map by removing its visual element (the + /** + * APIMethod: removeLayer + * Removes a layer from the map by removing its visual element (the * layer.div property), then removing it from the map's internal list * of layers, setting the layer's map property to null. * @@ -420,8 +550,9 @@ OpenLayers.Map.prototype = { * recognizes itself as the layer being removed, then it cycles through * its own personal list of popups, removing them from the map. * - * @param {OpenLayers.Layer} layer - * @param {Boolean} setNewBaseLayer Default is true + * Parameters: + * layer - {} + * setNewBaseLayer - {Boolean} Default is true */ removeLayer: function(layer, setNewBaseLayer) { if (setNewBaseLayer == null) { @@ -451,33 +582,40 @@ OpenLayers.Map.prototype = { }, /** - * @returns The number of layers attached to the map. - * @type int - */ + * APIMethod: getNumLayers + * + * Return: {Int} The number of layers attached to the map. + */ getNumLayers: function () { return this.layers.length; }, /** - * @returns The current (zero-based) index of the given layer in the map's - * layer stack. Returns -1 if the layer isn't on the map. - * - * @param {OpenLayers.Layer} layer - * @type int - */ + * APIMethod: getLayerIndex + * + * Parameters: + * layer - {} + * + * Return: + * {Integer} The current (zero-based) index of the given layer in the map's + * layer stack. Returns -1 if the layer isn't on the map. + */ getLayerIndex: function (layer) { return OpenLayers.Util.indexOf(this.layers, layer); }, - /** Move the given layer to the specified (zero-based) index in the layer - * list, changing its z-index in the map display. Use - * map.getLayerIndex() to find out the current index of a layer. Note - * that this cannot (or at least should not) be effectively used to - * raise base layers above overlays. - * - * @param {OpenLayers.Layer} layer - * @param {int} idx - */ + /** + * APIMethod: setLayerIndex + * Move the given layer to the specified (zero-based) index in the layer + * list, changing its z-index in the map display. Use + * map.getLayerIndex() to find out the current index of a layer. Note + * that this cannot (or at least should not) be effectively used to + * raise base layers above overlays. + * + * Parameters: + * layer - {} + * idx - {int} + */ setLayerIndex: function (layer, idx) { var base = this.getLayerIndex(layer); if (idx < 0) @@ -493,24 +631,30 @@ OpenLayers.Map.prototype = { } }, - /** Change the index of the given layer by delta. If delta is positive, - * the layer is moved up the map's layer stack; if delta is negative, - * the layer is moved down. Again, note that this cannot (or at least - * should not) be effectively used to raise base layers above overlays. - * - * @param {OpenLayers.Layer} layer - * @param {int} idx - */ + /** + * APIMethod: raiseLayer + * Change the index of the given layer by delta. If delta is positive, + * the layer is moved up the map's layer stack; if delta is negative, + * the layer is moved down. Again, note that this cannot (or at least + * should not) be effectively used to raise base layers above overlays. + * + * Paremeters: + * layer - {} + * idx - {int} + */ raiseLayer: function (layer, delta) { var idx = this.getLayerIndex(layer) + delta; this.setLayerIndex(layer, idx); }, - /** Allows user to specify one of the currently-loaded layers as the Map's - * new base layer. + /** + * APIMethod: setBaseLayer + * Allows user to specify one of the currently-loaded layers as the Map's + * new base layer. * - * @param {OpenLayers.Layer} newBaseLayer - * @param {Boolean} noEvent + * Parameters: + * newBaseLayer - {} + * noEvent - {Boolean} */ setBaseLayer: function(newBaseLayer, noEvent) { var oldExtent = null; @@ -520,7 +664,7 @@ OpenLayers.Map.prototype = { if (newBaseLayer != this.baseLayer) { - // is newBaseLayer an already loaded layer? + // is newBaseLayer an already loaded layer?m if (OpenLayers.Util.indexOf(this.layers, newBaseLayer) != -1) { // make the old base layer invisible @@ -569,19 +713,24 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @param {OpenLayers.Control} control - * @param {OpenLayers.Pixel} px - */ + * APIMethod: addControl + * + * Parameters: + * control - {} + * px - {} + */ addControl: function (control, px) { this.controls.push(control); this.addControlToMap(control, px); }, /** - * @private + * Method: addControlToMap * - * @param {OpenLayers.Control} control - * @param {OpenLayers.Pixel} px + * Parameters: + * + * control - {} + * px - {} */ addControlToMap: function (control, px) { // If a control doesn't have a div at this point, it belongs in the @@ -599,11 +748,15 @@ OpenLayers.Map.prototype = { }, /** - * @param {String} id ID of the control to return + * APIMethod: getControl * - * @returns The control from the map's list of controls which has a - * matching 'id'. If none found, returns null. - * @type OpenLayers.Control + * Parameters: + * id - {String} ID of the control to return. + * + * Return: + * {} The control from the map's list of controls + * which has a matching 'id'. If none found, + * returns null. */ getControl: function (id) { var returnControl = null; @@ -617,11 +770,14 @@ OpenLayers.Map.prototype = { return returnControl; }, - /** Remove a control from the map. Removes the control both from the map - * object's internal array of controls, as well as from the map's - * viewPort (assuming the control was not added outsideViewport) + /** + * APIMethod: removeControl + * Remove a control from the map. Removes the control both from the map + * object's internal array of controls, as well as from the map's + * viewPort (assuming the control was not added outsideViewport) * - * @param {OpenLayers.Control} control control to remove + * Parameters: + * control - {} The control to remove. */ removeControl: function (control) { //make sure control is non-null and actually part of our map @@ -643,9 +799,12 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @param {OpenLayers.Popup} popup - * @param {Boolean} exclusive If true, closes all other popups first - */ + * APIMethod: addPopup + * + * Parameters: + * popup - {} + * exclusive - {Boolean} If true, closes all other popups first + */ addPopup: function(popup, exclusive) { if (exclusive) { @@ -666,7 +825,10 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.Popup} popup + * APIMethod: removePopup + * + * Parameters: + * popup - {} */ removePopup: function(popup) { OpenLayers.Util.removeItem(this.popups, popup); @@ -688,14 +850,15 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @returns An OpenLayers.Size object that represents the size, in pixels, - * of the div into which OpenLayers has been loaded. - * - * Note: A clone() of this locally cached variable is returned, so - * as not to allow users to modify it. - * - * @type OpenLayers.Size - */ + * APIMethod: getSize + * + * Return: + * {} An object that represents the + * size, in pixels, of the div into which OpenLayers + * has been loaded. + * Note - A clone() of this locally cached variable is + * returned, so as not to allow users to modify it. + */ getSize: function () { var size = null; if (this.size != null) { @@ -705,10 +868,11 @@ OpenLayers.Map.prototype = { }, /** - * This function should be called by any external code which dynamically - * changes the size of the map div (because mozilla wont let us catch the - * "onresize" for an element) - */ + * APIMethod: updateSize + * This function should be called by any external code which dynamically + * changes the size of the map div (because mozilla wont let us catch + * the "onresize" for an element) + */ updateSize: function() { // the div might have moved on the page, also this.events.element.offsets = null; @@ -738,10 +902,11 @@ OpenLayers.Map.prototype = { }, /** - * @private + * Method: getCurrentSize * - * @returns A new OpenLayers.Size object with the dimensions of the map div - * @type OpenLayers.Size + * Return: + * {} A new object with the dimensions + * of the map div */ getCurrentSize: function() { @@ -762,11 +927,15 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.LonLat} center Default is this.getCenter() - * @param {float} resolution Default is this.getResolution() + * Method: calculateBounds * - * @returns A Bounds based on resolution, center, and current mapsize. - * @type OpenLayers.Bounds + * Parameters: + * center - {} Default is this.getCenter() + * resolution - {float} Default is this.getResolution() + * + * Return: + * {} A bounds based on resolution, center, and + * current mapsize. */ calculateBounds: function(center, resolution) { @@ -806,24 +975,33 @@ OpenLayers.Map.prototype = { /* */ /********************************************************/ /** - * @return {OpenLayers.LonLat} - */ + * APIMethod: getCenter + * + * Return: + * {} + */ getCenter: function () { return this.center; }, /** - * @return {int} - */ + * APIMethod: getZoom + * + * Return: + * {Integer} + */ getZoom: function () { return this.zoom; }, - /** Allows user to pan by a value of screen pixels + /** + * APIMethod: pan + * Allows user to pan by a value of screen pixels * - * @param {int} dx - * @param {int} dy + * Parameters: + * dx - {Integer} + * dy - {Integer} */ pan: function(dx, dy) { @@ -842,17 +1020,18 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.LonLat} lonlat - * @param {int} zoom - * @param {Boolean} dragging Specifies whether or not to - * trigger movestart/end events - * @param {Boolean} forceZoomChange - * Specifies whether or not to - * trigger zoom change events - * (needed on baseLayer change) - * - * TBD: reconsider forceZoomChange in 3.0 - */ + * APIMethod: setCenter + * + * Parameters: + * lonlat - {} + * zoom - {Integer} + * dragging - {Boolean} Specifies whether or not to trigger + * movestart/end events + * forceZoomChange - {Boolean} Specifies whether or not to trigger zoom + * change events (needed on baseLayer change) + * + * TBD: reconsider forceZoomChange in 3.0 + */ setCenter: function (lonlat, zoom, dragging, forceZoomChange) { if (!this.center && !this.isValidLonLat(lonlat)) { @@ -938,11 +1117,12 @@ OpenLayers.Map.prototype = { if (!dragging) { this.events.triggerEvent("moveend"); } }, - /** This function takes care to recenter the layerContainerDiv + /** + * Method: centerLayerContainer + * This function takes care to recenter the layerContainerDiv. * - * @private - * - * @param {OpenLayers.LonLat} lonlat + * Parameters: + * lonlat - {} */ centerLayerContainer: function (lonlat) { @@ -956,13 +1136,14 @@ OpenLayers.Map.prototype = { }, /** - * @private + * Method: isValidZoomLevel * - * @param {int} zoomLevel + * Parameters: + * zoomLevel - {Integer} * - * @returns Whether or not the zoom level passed in is non-null and + * Return: + * {Boolean} Whether or not the zoom level passed in is non-null and * within the min/max range of zoom levels. - * @type Boolean */ isValidZoomLevel: function(zoomLevel) { return ( (zoomLevel != null) && @@ -971,14 +1152,14 @@ OpenLayers.Map.prototype = { }, /** - * @private + * Method: isValidLonLat * - * @param {OpenLayers.LonLat} lonlat + * Parameters: + * lonlat - {} * - * @returns Whether or not the lonlat passed in is non-null and within - * the maxExtent bounds - * - * @type Boolean + * Return: + * {Boolean} Whether or not the lonlat passed in is non-null and within + * the maxExtent bounds */ isValidLonLat: function(lonlat) { var valid = false; @@ -998,8 +1179,10 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @returns The Projection of the base layer - * @type String + * APIMethod: getProjection + * + * Return: + * {String} The Projection of the base layer. */ getProjection: function() { var projection = null; @@ -1010,8 +1193,10 @@ OpenLayers.Map.prototype = { }, /** - * @returns The Map's Maximum Resolution - * @type String + * APIMethod: getMaxResolution + * + * Return: + * {String} The Map's Maximum Resolution */ getMaxResolution: function() { var maxResolution = null; @@ -1022,8 +1207,11 @@ OpenLayers.Map.prototype = { }, /** - * @type OpenLayers.Bounds - */ + * APIMethod: getMaxExtent + * + * Return: + * {} + */ getMaxExtent: function () { var maxExtent = null; if (this.baseLayer != null) { @@ -1033,9 +1221,11 @@ OpenLayers.Map.prototype = { }, /** - * @returns The total number of zoom levels that can be displayed by the + * APIMethod: getNumZoomLevels + * + * Return: + * {Integer} The total number of zoom levels that can be displayed by the * current baseLayer. - * @type int */ getNumZoomLevels: function() { var numZoomLevels = null; @@ -1057,10 +1247,12 @@ OpenLayers.Map.prototype = { /********************************************************/ /** - * @returns A Bounds object which represents the lon/lat bounds of the - * current viewPort. - * If no baselayer is set, returns null. - * @type OpenLayers.Bounds + * APIMethod: getExtent + * + * Return: + * {} A Bounds object which represents the lon/lat + * bounds of the current viewPort. + * If no baselayer is set, returns null. */ getExtent: function () { var extent = null; @@ -1071,9 +1263,11 @@ OpenLayers.Map.prototype = { }, /** - * @returns The current resolution of the map. - * If no baselayer is set, returns null. - * @type float + * APIMethod: getResolution + * + * Return: + * {Float} The current resolution of the map. + * If no baselayer is set, returns null. */ getResolution: function () { var resolution = null; @@ -1084,9 +1278,11 @@ OpenLayers.Map.prototype = { }, /** - * @returns The current scale denominator of the map. - * If no baselayer is set, returns null. - * @type float + * APIMethod: getScale + * + * Return: + * {Float} The current scale denominator of the map. + * If no baselayer is set, returns null. */ getScale: function () { var scale = null; @@ -1100,11 +1296,14 @@ OpenLayers.Map.prototype = { /** - * @param {OpenLayers.Bounds} bounds - * - * @returns A suitable zoom level for the specified bounds. - * If no baselayer is set, returns null. - * @type int + * APIMethod: getZoomForExteng + * + * Parameters: + * bounds - {} + * + * Return: + * {Integer} A suitable zoom level for the specified bounds. + * If no baselayer is set, returns null. */ getZoomForExtent: function (bounds) { var zoom = null; @@ -1115,11 +1314,14 @@ OpenLayers.Map.prototype = { }, /** - * @param {float} resolution - * - * @returns A suitable zoom level for the specified resolution. - * If no baselayer is set, returns null. - * @type int + * APIMethod: getZoomForResolution + * + * Parameter: + * resolution - {Float} + * + * Return: + * {Integer} A suitable zoom level for the specified resolution. + * If no baselayer is set, returns null. */ getZoomForResolution: function(resolution) { var zoom = null; @@ -1139,9 +1341,12 @@ OpenLayers.Map.prototype = { /* */ /********************************************************/ - /** Zoom to a specific zoom level + /** + * APIMethod: zoomTo + * Zoom to a specific zoom level * - * @param {int} zoom + * Parameters: + * zoom - {Integer} */ zoomTo: function(zoom) { if (this.isValidZoomLevel(zoom)) { @@ -1150,22 +1355,31 @@ OpenLayers.Map.prototype = { }, /** - * @param {int} zoom + * APIMethod: zoomIn + * + * Parameters: + * zoom - {int} */ zoomIn: function() { this.zoomTo(this.getZoom() + 1); }, /** - * @param {int} zoom + * APIMethod: zoomOut + * + * Parameters: + * zoom - {int} */ zoomOut: function() { this.zoomTo(this.getZoom() - 1); }, - /** Zoom to the passed in bounds, recenter + /** + * APIMethod: zoomToExtent + * Zoom to the passed in bounds, recenter * - * @param {OpenLayers.Bounds} bounds + * Parameters: + * bounds - {} */ zoomToExtent: function(bounds) { var center = bounds.getCenterLonLat(); @@ -1194,15 +1408,20 @@ OpenLayers.Map.prototype = { this.setCenter(center, this.getZoomForExtent(bounds)); }, - /** Zoom to the full extent and recenter. + /** + * APIMethod: zoomToMaxExtent + * Zoom to the full extent and recenter. */ zoomToMaxExtent: function() { this.zoomToExtent(this.getMaxExtent()); }, - /** zoom to a specified scale + /** + * APIMethod: zoomToScale + * Zoom to a specified scale * - * @param {float} scale + * Parameters: + * scale - {float} */ zoomToScale: function(scale) { var res = OpenLayers.Util.getResolutionFromScale(scale, @@ -1233,14 +1452,16 @@ OpenLayers.Map.prototype = { // /** - * @param {OpenLayers.Pixel} viewPortPx - * - * @returns An OpenLayers.LonLat which is the passed-in view port - * OpenLayers.Pixel, translated into lon/lat by the - * current base layer - * @type OpenLayers.LonLat - * @private - */ + * APIMethod: getLonLatFromViewPortPx + * + * Parameters: + * viewPortPx - {} + * + * Return: + * {} An OpenLayers.LonLat which is the passed-in view + * port , translated into lon/lat + * by the current base layer. + */ getLonLatFromViewPortPx: function (viewPortPx) { var lonlat = null; if (this.baseLayer != null) { @@ -1250,14 +1471,16 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.LonLat} lonlat - * - * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, - * translated into view port pixels by the - * current base layer - * @type OpenLayers.Pixel - * @private - */ + * APIMethod: getViewPortPxFromLonLat + * + * Parameters: + * lonlat - {} + * + * Return: + * {} An OpenLayers.Pixel which is the passed-in + * , translated into view port + * pixels by the current base layer. + */ getViewPortPxFromLonLat: function (lonlat) { var px = null; if (this.baseLayer != null) { @@ -1272,24 +1495,30 @@ OpenLayers.Map.prototype = { // /** - * @param {OpenLayers.Pixel} pixel + * APIMethod: getLonLatFromPixel + * + * Parameters: + * px - {} * - * @returns An OpenLayers.LonLat corresponding to the given - * OpenLayers.Pixel, translated into lon/lat by the - * current base layer - * @type OpenLayers.LonLat + * Return: + * {} An OpenLayers.LonLat corresponding to the given + * OpenLayers.Pixel, translated into lon/lat by the + * current base layer */ getLonLatFromPixel: function (px) { return this.getLonLatFromViewPortPx(px); }, /** - * @param {OpenLayers.LonLat} lonlat - * - * @returns An OpenLayers.Pixel corresponding to the OpenLayers.LonLat - * translated into view port pixels by the - * current base layer - * @type OpenLayers.Pixel + * APIMethod: getPixelFromLonLat + * + * Parameters: + * lonlat - {} + * + * Return: + * {} An OpenLayers.Pixel corresponding to the + * translated into view port + * pixels by the current base layer. */ getPixelFromLonLat: function (lonlat) { return this.getViewPortPxFromLonLat(lonlat); @@ -1302,12 +1531,14 @@ OpenLayers.Map.prototype = { // /** - * @private + * APIMethod: getViewPortPxFromLayerPx * - * @param {OpenLayers.Pixel} layerPx + * Parameters: + * layerPx - {} * - * @returns Layer Pixel translated into ViewPort Pixel coordinates - * @type OpenLayers.Pixel + * Return: + * {} Layer Pixel translated into ViewPort Pixel + * coordinates */ getViewPortPxFromLayerPx:function(layerPx) { var viewPortPx = null; @@ -1320,12 +1551,14 @@ OpenLayers.Map.prototype = { }, /** - * @private + * APIMethod: getLayerPxFromViewPortPx * - * @param {OpenLayers.Pixel} viewPortPx + * Parameters: + * viewPortPx - {} * - * @returns ViewPort Pixel translated into Layer Pixel coordinates - * @type OpenLayers.Pixel + * Return: + * {} ViewPort Pixel translated into Layer Pixel + * coordinates */ getLayerPxFromViewPortPx:function(viewPortPx) { var layerPx = null; @@ -1345,10 +1578,14 @@ OpenLayers.Map.prototype = { // /** - * @param {OpenLayers.Pixel} px - * - * @type OpenLayers.LonLat - */ + * APIMethod: getLonLatFromLayerPx + * + * Parameters: + * px - {} + * + * Return: + * {} + */ getLonLatFromLayerPx: function (px) { //adjust for displacement of layerContainerDiv px = this.getViewPortPxFromLayerPx(px); @@ -1356,12 +1593,16 @@ OpenLayers.Map.prototype = { }, /** - * @param {OpenLayers.LonLat} lonlat - * - * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, - * translated into layer pixels by the current base layer - * @type OpenLayers.Pixel - */ + * APIMethod: getLayerPxFromLonLat + * + * Parameters: + * lonlat - {} lonlat + * + * Return: + * {} An OpenLayers.Pixel which is the passed-in + * , translated into layer pixels + * by the current base layer + */ getLayerPxFromLonLat: function (lonlat) { //adjust for displacement of layerContainerDiv var px = this.getViewPortPxFromLonLat(lonlat); diff --git a/lib/OpenLayers/Marker.js b/lib/OpenLayers/Marker.js index 252868237b..e83002beb8 100644 --- a/lib/OpenLayers/Marker.js +++ b/lib/OpenLayers/Marker.js @@ -4,32 +4,46 @@ /** - * @class * @requires OpenLayers/Events.js * @requires OpenLayers/Icon.js + * + * Class: OpenLayers.Marker + * Instances of OpenLayers.Marker are a combination of a + * and an . */ OpenLayers.Marker = OpenLayers.Class.create(); OpenLayers.Marker.prototype = { - /** @type OpenLayers.Icon */ - icon: null, + /** + * Property: icon + * {} + */ + icon: null, - /** location of object - * @type OpenLayers.LonLat */ - lonlat: null, - - /** @type OpenLayers.Events*/ - events: null, - - /** @type OpenLayers.Map */ - map: null, + /** + * Property: lonlat + * {} location of object + */ + lonlat: null, /** - * @constructor - * - * @param {OpenLayers.Icon} icon - * @param {OpenLayers.LonLat lonlat - */ + * Property: events + * {} + */ + events: null, + + /** + * Property: map + * {} + */ + map: null, + + /** + * Constructor: OpenLayers.Marker + * Paraemeters: + * icon - {} + * lonlat - {} + */ initialize: function(lonlat, icon) { this.lonlat = lonlat; @@ -58,18 +72,26 @@ OpenLayers.Marker.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: draw + * Calls draw on the icon, and returns that output. * - * @return A new DOM Image with this marker's icon set at the - * location passed-in - * @type DOMElement + * Parameters: + * px - {} + * + * Return: + * {DOMElement} A new DOM Image with this marker's icon set at the + * location passed-in */ draw: function(px) { return this.icon.draw(px); }, /** - * @param {OpenLayers.Pixel} px + * Method: moveTo + * Move the marker to the new location. + * + * Parameters: + * px - {} */ moveTo: function (px) { if ((px != null) && (this.icon != null)) { @@ -79,8 +101,10 @@ OpenLayers.Marker.prototype = { }, /** - * @returns Whether or not the marker is currently visible on screen. - * @type Boolean + * Method: onScreen + * + * Return: + * {Boolean} Whether or not the marker is currently visible on screen. */ onScreen:function() { @@ -93,7 +117,10 @@ OpenLayers.Marker.prototype = { }, /** - * @param {float} inflate + * Method: inflate + * + * Parameters: + * inflate - {float} */ inflate: function(inflate) { if (this.icon) { @@ -103,18 +130,23 @@ OpenLayers.Marker.prototype = { } }, - /** Change the opacity of the marker by changin the opacity of + /** + * Method: setOpacity + * Change the opacity of the marker by changin the opacity of * its icon * - * @param {float} opacity Specified as fraction (0.4, etc) + * Parameters: + * opacity - {float} Specified as fraction (0.4, etc) */ setOpacity: function(opacity) { this.icon.setOpacity(opacity); }, - /** Hide or show the icon + /** + * Method: display + * Hide or show the icon * - * @param {Boolean} display + * display - {Boolean} */ display: function(display) { this.icon.display(display); @@ -125,9 +157,12 @@ OpenLayers.Marker.prototype = { }; -/** - * @returns A default OpenLayers.Icon to use for a marker - * @type OpenLayers.Icon +/** + * Function: defaultIcon + * Creates a default . + * + * Returns: + * {} A default OpenLayers.Icon to use for a marker */ OpenLayers.Marker.defaultIcon = function() { var url = OpenLayers.Util.getImagesLocation() + "marker.png"; diff --git a/lib/OpenLayers/Marker/Box.js b/lib/OpenLayers/Marker/Box.js index 8501439560..08c4dd83bd 100644 --- a/lib/OpenLayers/Marker/Box.js +++ b/lib/OpenLayers/Marker/Box.js @@ -4,26 +4,36 @@ /** - * @class - * * @requires OpenLayers/Marker.js + * + * Class: OpenLayers.Marker.Box + * + * Inherits from: + * - */ OpenLayers.Marker.Box = OpenLayers.Class.create(); OpenLayers.Marker.Box.prototype = OpenLayers.Class.inherit( OpenLayers.Marker, { - /** @type OpenLayers.Bounds */ - bounds: null, + /** + * Property: bounds + * {} + */ + bounds: null, - /** @type DOMElement */ - div: null, + /** + * Property: div + * {DOMElement} + */ + div: null, /** - * @constructor + * Constructor: OpenLayers.Marker.Box * - * @param {OpenLayers.Bounds} bounds - * @param {String} borderColor - * @param {int} borderWidth + * Parameters: + * bounds - {} + * borderColor - {String} + * borderWidth - {int} */ initialize: function(bounds, borderColor, borderWidth) { this.bounds = bounds; @@ -34,7 +44,7 @@ OpenLayers.Marker.Box.prototype = }, /** - * + * Method: destroy */ destroy: function() { @@ -44,10 +54,13 @@ OpenLayers.Marker.Box.prototype = OpenLayers.Marker.prototype.destroy.apply(this, arguments); }, - /** Allow the user to change the box's color and border width + /** + * Method: setBorder + * Allow the user to change the box's color and border width * - * @param {String} color Default is "red" - * @param {int} width Default is 2 + * Parameters: + * color - {String} Default is "red" + * width - {int} Default is 2 */ setBorder: function (color, width) { if (!color) { @@ -60,12 +73,15 @@ OpenLayers.Marker.Box.prototype = }, /** - * @param {OpenLayers.Pixel} px - * @param {OpenLayers.Size} sz + * Method: draw * - * @return A new DOM Image with this marker´s icon set at the + * Parameters: + * px - {} + * sz - {} + * + * Return: + * {DOMElement} A new DOM Image with this marker´s icon set at the * location passed-in - * @type DOMElement */ draw: function(px, sz) { OpenLayers.Util.modifyDOMElement(this.div, null, px, sz); @@ -73,8 +89,10 @@ OpenLayers.Marker.Box.prototype = }, /** - * @returns Whether or not the marker is currently visible on screen. - * @type Boolean + * Method: onScreen + * + * Rreturn: + * {Boolean} Whether or not the marker is currently visible on screen. */ onScreen:function() { var onScreen = false; @@ -85,9 +103,12 @@ OpenLayers.Marker.Box.prototype = return onScreen; }, - /** Hide or show the icon + /** + * Method: display + * Hide or show the icon * - * @param {Boolean} display + * Parameters: + * display - {Boolean} */ display: function(display) { this.div.style.display = (display) ? "" : "none"; diff --git a/lib/OpenLayers/Popup.js b/lib/OpenLayers/Popup.js index 00f4ede767..ff3477f5c9 100644 --- a/lib/OpenLayers/Popup.js +++ b/lib/OpenLayers/Popup.js @@ -4,7 +4,7 @@ /** - * @class + * Class: OpenLayers.Popup */ OpenLayers.Popup = OpenLayers.Class.create(); @@ -16,55 +16,94 @@ OpenLayers.Popup.BORDER = "0px"; OpenLayers.Popup.prototype = { - /** @type OpenLayers.Events*/ - events: null, + /** + * Property: events + * {} + */ + events: null, - /** @type String */ + /** Property: id + * {String} + */ id: "", - /** @type OpenLayers.LonLat */ - lonlat: null, - - /** @type DOMElement */ - div: null, - - /** @type OpenLayers.Size*/ - size: null, - - /** @type String */ - contentHTML: "", - - /** @type String */ - backgroundColor: "", - - /** @type float */ - opacity: "", - - /** @type String */ - border: "", - - /** @type DOMElement */ - contentDiv:null, - - /** @type DOMElement */ - groupDiv:null, - - /** @type int */ - padding: 5, - - - /** this gets set in Map.js when the popup is added to the map - * @type OpenLayers.Map */ - map: null, + /** + * Property: lonlat + * {} + */ + lonlat: null, /** - * @constructor + * Property: div + * {DOMElement} + */ + div: null, + + /** + * Property: size + * {} + */ + size: null, + + /** + * Property: contentHTML + * {String} + */ + contentHTML: "", + + /** + * Property: backgroundColor + * {String} + */ + backgroundColor: "", + + /** + * Property: opacity + * {float} + */ + opacity: "", + + /** + * Property: border + * {String} + */ + border: "", + + /** + * Property: contentDiv + * {DOMElement} + */ + contentDiv: null, + + /** + * Property: groupDiv + * {DOMElement} + */ + groupDiv: null, + + /** + * Property: padding + * {int} + */ + padding: 5, + + + /** + * Property: map + * {} this gets set in Map.js when the popup is added to the map + */ + map: null, + + /** + * Constructor: OpenLayers.Popup + * Create a popup. * - * @param {String} id - * @param {OpenLayers.LonLat} lonlat - * @param {OpenLayers.Size} size - * @param {String} contentHTML - * @param {Boolean} closeBox + * Parameters: + * id - {String} + * lonlat - {} + * size - {} + * contentHTML - {String} + * closeBox - {Boolean} */ initialize:function(id, lonlat, size, contentHTML, closeBox) { if (id == null) { @@ -125,7 +164,9 @@ OpenLayers.Popup.prototype = { }, /** - */ + * Method: destroy + * nullify references to prevent circular references and memory leaks + */ destroy: function() { if (this.map != null) { this.map.removePopup(this); @@ -137,10 +178,13 @@ OpenLayers.Popup.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * method: draw * - * @returns Reference to a div that contains the drawn popup - * @type DOMElement + * Parameters: + * px - {} + * + * Return: + * {DOMElement} Reference to a div that contains the drawn popup */ draw: function(px) { if (px == null) { @@ -160,8 +204,9 @@ OpenLayers.Popup.prototype = { }, /** + * Method: updatePosition * if the popup has a lonlat and its map members set, - * then have it move itself to its proper position + * then have it move itself to its proper position */ updatePosition: function() { if ((this.lonlat) && (this.map)) { @@ -171,7 +216,10 @@ OpenLayers.Popup.prototype = { }, /** - * @param {OpenLayers.Pixel} px + * Method: moveTo + * + * Parameters: + * px - {} */ moveTo: function(px) { if ((px != null) && (this.div != null)) { @@ -181,36 +229,41 @@ OpenLayers.Popup.prototype = { }, /** - * @returns Boolean indicating whether or not the popup is visible - * @type Boolean + * method: visible + * + * Returns: + * {Boolean} Boolean indicating whether or not the popup is visible */ visible: function() { return OpenLayers.Element.visible(this.div); }, /** - * + * Method: toggle */ toggle: function() { OpenLayers.Element.toggle(this.div); }, /** - * + * Method: show */ show: function() { OpenLayers.Element.show(this.div); }, /** - * + * Method: hide */ hide: function() { OpenLayers.Element.hide(this.div); }, /** - * @param {OpenLayers.Size} size + * Method: setSize + * + * Parameters: + * size - {} */ setSize:function(size) { if (size != undefined) { @@ -228,7 +281,10 @@ OpenLayers.Popup.prototype = { }, /** - * @param {String} color + * Method: setBackgroundColor + * + * Parameters: + * color - {String} */ setBackgroundColor:function(color) { if (color != undefined) { @@ -241,7 +297,10 @@ OpenLayers.Popup.prototype = { }, /** - * @param {float} opacity + * Method: setOpacity + * + * Parameters: + * opacity - {float} */ setOpacity:function(opacity) { if (opacity != undefined) { @@ -258,7 +317,10 @@ OpenLayers.Popup.prototype = { }, /** - * @param {int} border + * Method: setBorder + * + * Parameters: + * border - {int} */ setBorder:function(border) { if (border != undefined) { @@ -271,7 +333,10 @@ OpenLayers.Popup.prototype = { }, /** - * @param {String} contentHTML + * Method: setContentHTML + * + * Parameters: + * contentHTML - {String} */ setContentHTML:function(contentHTML) { if (contentHTML != null) { @@ -285,7 +350,11 @@ OpenLayers.Popup.prototype = { - /** Do this in a separate function so that subclasses can + /** + * Method: registerEvents + * Registers events on the popup. + * + * Do this in a separate function so that subclasses can * choose to override it if they wish to deal differently * with mouse events * @@ -313,22 +382,28 @@ OpenLayers.Popup.prototype = { this.events.register("dblclick", this, this.ondblclick); }, - /** When mouse goes down within the popup, make a note of + /** + * Method: onmousedown + * When mouse goes down within the popup, make a note of * it locally, and then do not propagate the mousedown * (but do so safely so that user can select text inside) * - * @param {Event} evt + * Parameters: + * evt - {Event} */ onmousedown: function (evt) { this.mousedown = true; OpenLayers.Event.stop(evt, true); }, - /** If the drag was started within the popup, then + /** + * Method: onmousemove + * If the drag was started within the popup, then * do not propagate the mousemove (but do so safely * so that user can select text inside) * - * @param {Event} evt + * Parameters: + * evt - {Event} */ onmousemove: function (evt) { if (this.mousedown) { @@ -336,12 +411,15 @@ OpenLayers.Popup.prototype = { } }, - /** When mouse comes up within the popup, after going down + /** + * Method: onmouseup + * When mouse comes up within the popup, after going down * in it, reset the flag, and then (once again) do not * propagate the event, but do so safely so that user can * select text inside * - * @param {Event} evt + * Parameters: + * evt - {Event} */ onmouseup: function (evt) { if (this.mousedown) { @@ -350,28 +428,35 @@ OpenLayers.Popup.prototype = { } }, - /** Ignore clicks, but allowing default browser handling + /** + * Method: onclick + * Ignore clicks, but allowing default browser handling * - * @param {Event} evt + * Parameters: + * evt - {Event} */ onclick: function (evt) { OpenLayers.Event.stop(evt, true); }, - /** When mouse goes out of the popup set the flag to false so that + /** + * Method: onmouseout + * When mouse goes out of the popup set the flag to false so that * if they let go and then drag back in, we won't be confused. * - * @param {Event} evt - * - * @type Boolean + * Parameters: + * evt - {Event} */ onmouseout: function (evt) { this.mousedown = false; }, - /** Ignore double-clicks, but allowing default browser handling + /** + * Method: ondblclick + * Ignore double-clicks, but allowing default browser handling * - * @param {Event} evt + * Parameters: + * evt - {Event} */ ondblclick: function (evt) { OpenLayers.Event.stop(evt, true); diff --git a/lib/OpenLayers/Popup/Anchored.js b/lib/OpenLayers/Popup/Anchored.js index 0b5c628ac3..8baa7f299e 100644 --- a/lib/OpenLayers/Popup/Anchored.js +++ b/lib/OpenLayers/Popup/Anchored.js @@ -4,35 +4,44 @@ /** - * @class - * * @requires OpenLayers/Popup.js + * + * Class: OpenLayers.Popup.Anchored + * + * Inherits from: + * - */ OpenLayers.Popup.Anchored = OpenLayers.Class.create(); OpenLayers.Popup.Anchored.prototype = OpenLayers.Class.inherit( OpenLayers.Popup, { - /** "lr", "ll", "tr", "tl" - relative position of the popup. - * @type String */ + /** + * Parameter: relativePosition + * {String} Relative position of the popup ("lr", "ll", "tr", or "tl") + */ relativePosition: null, - /** Object which must have expose a 'size' (OpenLayers.Size) and - * 'offset' (OpenLayers.Pixel) - * @type Object */ + /** + * Parameter: anchor + * {Object} Object to which we'll anchor the popup. + * Must expose a 'size' () and + * 'offset' () + */ anchor: null, /** - * @constructor + * Constructor: OpenLayers.Popup.Anchored * - * @param {String} id - * @param {OpenLayers.LonLat} lonlat - * @param {OpenLayers.Size} size - * @param {String} contentHTML - * @param {Object} anchor Object which must expose a + * Parameters: + * id - {String} + * lonlat - {} + * size - {} + * contentHTML - {String} + * anchor - {Object} Object which must expose a * - 'size' (OpenLayers.Size) and * - 'offset' (OpenLayers.Pixel) * (this is generally an OpenLayers.Icon) - * @param {Boolean} closeBox + * closeBox - {Boolean} */ initialize:function(id, lonlat, size, contentHTML, anchor, closeBox) { var newArguments = new Array(id, lonlat, size, contentHTML, closeBox); @@ -44,11 +53,14 @@ OpenLayers.Popup.Anchored.prototype = }, /** - * @param {OpenLayers.Pixel} px - * - * @returns Reference to a div that contains the drawn popup - * @type DOMElement - */ + * Method: draw + * + * Parameters: + * px - {} + * + * Return: + * {DOMElement} Reference to a div that contains the drawn popup + */ draw: function(px) { if (px == null) { if ((this.lonlat != null) && (this.map != null)) { @@ -63,13 +75,14 @@ OpenLayers.Popup.Anchored.prototype = }, /** - * @private + * Method: calculateRelativePosition * - * @param {OpenLayers.Pixel} px + * Parameters: + * px - {} * - * @returns The relative position ("br" "tr" "tl "bl") at which the popup - * should be placed - * @type String + * Return: + * {String} The relative position ("br" "tr" "tl "bl") at which the popup + * should be placed */ calculateRelativePosition:function(px) { var lonlat = this.map.getLonLatFromLayerPx(px); @@ -81,7 +94,10 @@ OpenLayers.Popup.Anchored.prototype = }, /** - * @param {OpenLayers.Pixel} px + * Method: moveTo + * + * Parameters: + * px - {} */ moveTo: function(px) { @@ -92,7 +108,10 @@ OpenLayers.Popup.Anchored.prototype = }, /** - * @param {OpenLayers.Size} size + * Method: setSize + * + * Parameters: + * size - {} */ setSize:function(size) { OpenLayers.Popup.prototype.setSize.apply(this, arguments); @@ -104,13 +123,14 @@ OpenLayers.Popup.Anchored.prototype = }, /** - * @private + * Method: calculateNewPx * - * @param {OpenLayers.Pixel} px + * Parameters: + * px - {} * - * @returns The the new px position of the popup on the screen - * relative to the passed-in px - * @type OpenLayers.Pixel + * Return: + * {} The the new px position of the popup on the screen + * relative to the passed-in px */ calculateNewPx:function(px) { var newPx = px.offset(this.anchor.offset); @@ -124,5 +144,6 @@ OpenLayers.Popup.Anchored.prototype = return newPx; }, + /** @final @type String */ CLASS_NAME: "OpenLayers.Popup.Anchored" }); diff --git a/lib/OpenLayers/Popup/AnchoredBubble.js b/lib/OpenLayers/Popup/AnchoredBubble.js index 17b6b7714b..f44d48bab6 100644 --- a/lib/OpenLayers/Popup/AnchoredBubble.js +++ b/lib/OpenLayers/Popup/AnchoredBubble.js @@ -4,43 +4,57 @@ /** - * @class - * * @requires OpenLayers/Popup/Anchored.js + * + * Class: OpenLayers.Popup.AnchoredBubble + * + * Inherits from: + * - */ OpenLayers.Popup.AnchoredBubble = OpenLayers.Class.create(); -//Border space for the rico corners +/** + * Constant: CORNER_SIZE + * {Integer} 5. Border space for the RICO corners + */ OpenLayers.Popup.AnchoredBubble.CORNER_SIZE = 5; OpenLayers.Popup.AnchoredBubble.prototype = OpenLayers.Class.inherit( OpenLayers.Popup.Anchored, { + /** + * Property: rounded + * {Boolean} Has the popup been rounded yet? + */ rounded: false, /** - * @constructor - * - * @param {String} id - * @param {OpenLayers.LonLat} lonlat - * @param {OpenLayers.Size} size - * @param {String} contentHTML - * @param {Object} anchor Object which must expose a - * - 'size' (OpenLayers.Size) and - * - 'offset' (OpenLayers.Pixel) - * (this is generally an OpenLayers.Icon) - * @param {Boolean} closeBox - */ + * Constructor: OpenLayers.Popup.AnchoredBubble + * + * Parameters: + * id - {String} + * lonlat - {} + * size - {} + * contentHTML - {String} + * anchor {Object} Object to which we'll anchor the popup. + * Must expose a 'size' () and + * 'offset' () + * (Note that this is generally an ) + * closeBox {Boolean} + */ initialize:function(id, lonlat, size, contentHTML, anchor, closeBox) { OpenLayers.Popup.Anchored.prototype.initialize.apply(this, arguments); }, /** - * @param {OpenLayers.Pixel} px - * - * @returns Reference to a div that contains the drawn popup - * @type DOMElement - */ + * Method: draw + * + * Parameters: + * px - {} + * + * Return: + * {DOMElement} Reference to a div that contains the drawn popup + */ draw: function(px) { OpenLayers.Popup.Anchored.prototype.draw.apply(this, arguments); @@ -58,8 +72,11 @@ OpenLayers.Popup.AnchoredBubble.prototype = }, /** - * @param {OpenLayers.Size} size - */ + * APIMethod: setSize + * + * Parameters: + * size - {} + */ setSize:function(size) { OpenLayers.Popup.Anchored.prototype.setSize.apply(this, arguments); @@ -81,7 +98,10 @@ OpenLayers.Popup.AnchoredBubble.prototype = }, /** - * @param {String} color + * APIMethod: setBackgroundColor + * + * Parameters: + * color - {String} */ setBackgroundColor:function(color) { if (color != undefined) { @@ -97,7 +117,10 @@ OpenLayers.Popup.AnchoredBubble.prototype = }, /** - * @param {float} opacity + * APIMethod: setOpacity + * + * Parameters: + * opacity - {float} */ setOpacity:function(opacity) { if (opacity != undefined) { @@ -111,22 +134,26 @@ OpenLayers.Popup.AnchoredBubble.prototype = } }, - /** Bubble Popups can not have a border + /** + * Method: setBorder * - * @param {int} border + * Always sets border to 0. Bubble Popups can not have a border. + * + * Parameters: + * border - {Integer} */ setBorder:function(border) { this.border = 0; }, /** - * @private + * Method: setRicoCorners * - * @param {Boolean} firstTime Is this the first time the corners are being - * rounded? - * - * update the rico corners according to the popup's - * current relative postion + * Update RICO corners according to the popup's current relative postion. + * + * Parameters: + * firstTime - {Boolean} Is this the first time the corners are being + * rounded? */ setRicoCorners:function(firstTime) { @@ -147,11 +174,10 @@ OpenLayers.Popup.AnchoredBubble.prototype = }, /** - * @private - * - * @returns The proper corners string ("tr tl bl br") for rico - * to round - * @type String + * Method: getCornersToRound + * + * Return: + * {String} The proper corners string ("tr tl bl br") for rico to round */ getCornersToRound:function() { @@ -164,5 +190,6 @@ OpenLayers.Popup.AnchoredBubble.prototype = return corners.join(" "); }, + /** @final @type String */ CLASS_NAME: "OpenLayers.Popup.AnchoredBubble" }); diff --git a/lib/OpenLayers/Renderer.js b/lib/OpenLayers/Renderer.js index 46be4d6196..4c8796724e 100644 --- a/lib/OpenLayers/Renderer.js +++ b/lib/OpenLayers/Renderer.js @@ -3,7 +3,8 @@ * for the full text of the license. */ /** - * @class Renderer is the base class for all renderers. + * Class: Renderer + * This is the base class for all renderers. * * This is based on a merger code written by Paul Spencer and Bertil Chapuis. * It is largely composed of virtual functions that are to be implemented @@ -21,34 +22,48 @@ OpenLayers.Renderer = OpenLayers.Class.create(); OpenLayers.Renderer.prototype = { - /** @type DOMElement */ + /** + * Property: container + * {DOMElement} + */ container: null, - /** @type OpenLayers.Bounds */ + /** + * Property: extent + * {} + */ extent: null, - /** @type OpenLayers.Size */ + /** + * Property: size + * {} + */ size: null, - /** cache of current map resolution - * @type float */ + /** + * Property: resolution + * {Float} cache of current map resolution + */ resolution: null, - /** Reference to the map -- this is set in Vector's setMap() - * @type OpenLayers.Map */ + /** + * Property: map + * {} Reference to the map -- this is set in Vector's setMap() + */ map: null, /** - * @constructor - * - * @param {String} containerID + * Constructor: OpenLayers.Renderer + * + * Parameters: + * containerID - {} */ initialize: function(containerID) { this.container = $(containerID); }, /** - * + * APIMethod: destroy */ destroy: function() { this.container = null; @@ -59,23 +74,26 @@ OpenLayers.Renderer.prototype = }, /** + * APIMethod: supported * This should be overridden by specific subclasses * - * @returns Whether or not the browser supports the VML renderer - * @type Boolean + * Returns: + * {Boolean} Whether or not the browser supports the renderer class */ supported: function() { return false; }, /** + * Method: setExtent * Set the visible part of the layer. * * Resolution has probably changed, so we nullify the resolution * cache (this.resolution) -- this way it will be re-computed when * next it is needed. * - * @param {OpenLayers.Bounds} extent + * Parameters: + * extent - {} */ setExtent: function(extent) { this.extent = extent.clone(); @@ -83,37 +101,42 @@ OpenLayers.Renderer.prototype = }, /** + * Method: setSize * Sets the size of the drawing surface. * * Resolution has probably changed, so we nullify the resolution * cache (this.resolution) -- this way it will be re-computed when * next it is needed. * - * @param {OpenLayers.Size} size + * Parameters: + * size - {} */ setSize: function(size) { this.size = size.clone(); this.resolution = null; }, - /** Uses cached copy of resolution if available to minimize computing + /** + * Method: getResolution + * Uses cached copy of resolution if available to minimize computing * - * @returns The current map's resolution - * @type float + * Returns: + * The current map's resolution */ getResolution: function() { this.resolution = this.resolution || this.map.getResolution(); return this.resolution; }, - /** + /** + * Method: drawFeature * Draw the feature. The optional style argument can be used * to override the feature's own style. This method should only * be called from layer.drawFeature(). * - * @param {OpenLayers.Feature.Vector} feature - * @param {Object} style - * @private + * Parameters: + * feature - {} + * style - {} */ drawFeature: function(feature, style) { if(style == null) { @@ -124,45 +147,47 @@ OpenLayers.Renderer.prototype = /** - * virtual function + * Method: drawGeometry * * Draw a geometry. This should only be called from the renderer itself. * Use layer.drawFeature() from outside the renderer. + * virtual function * - * @param geometry {OpenLayers.Geometry} - * @param style {Object} - * @param {String} featureId - * @private + * Parameters: + * geometry - {} + * style - {Object} + * featureId - {} */ drawGeometry: function(geometry, style, featureId) {}, /** - * virtual function - * - * Clear all vectors from the renderer - * @private + * Method: clear + * Clear all vectors from the renderer. + * virtual function. */ clear: function() {}, /** - * virtual function - * + * Method: getFeatureIdFromEvent * Returns a feature id from an event on the renderer. * How this happens is specific to the renderer. This should be * called from layer.getFeatureFromEvent(). + * Virtual function. * - * @param evt {OpenLayers.Event} + * Parameters: + * evt - {} * - * @returns A feature id or null - * @type String - * @private + * Returns: + * {String} A feature id or null. */ getFeatureIdFromEvent: function(evt) {}, /** + * Method: eraseFeatures * This is called by the layer to erase features - * @param {Array(OpenLayers.Feature.Vector)} features - * @private + * + * Parameters: + * features - {Array()} */ eraseFeatures: function(features) { if(!(features instanceof Array)) { @@ -174,12 +199,12 @@ OpenLayers.Renderer.prototype = }, /** - * virtual function + * Method: eraseGeometry + * Remove a geometry from the renderer (by id). + * virtual function. * - * Remove a geometry from the renderer (by id) - * - * @param geometry {OpenLayers.Geometry} - * @private + * Parameters: + * geometry - {} */ eraseGeometry: function(geometry) {}, diff --git a/lib/OpenLayers/Renderer/Elements.js b/lib/OpenLayers/Renderer/Elements.js index 27eb0a9c78..9058fc29e5 100644 --- a/lib/OpenLayers/Renderer/Elements.js +++ b/lib/OpenLayers/Renderer/Elements.js @@ -3,8 +3,9 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Renderer.js * + * Class: OpenLayers.Renderer.Elements * This is another virtual class in that it should never be instantiated by * itself as a Renderer. It exists because there is *tons* of shared * functionality between different vector libraries which use nodes/elements @@ -15,25 +16,36 @@ * element-based renderer. The details of creating each node and drawing the * paths are of course different, but the machinery is the same. * - * @requires OpenLayers/Renderer.js + * Inherits: + * - */ OpenLayers.Renderer.Elements = OpenLayers.Class.create(); OpenLayers.Renderer.Elements.prototype = OpenLayers.Class.inherit(OpenLayers.Renderer, { - /** @type DOMElement */ + /** + * Property: rendererRoot + * {DOMElement} + */ rendererRoot: null, - /** @type DOMElement */ + /** + * Property: root + * {DOMElement} + */ root: null, - /** @type String */ + /** + * Property: xmlns + * {String} + */ xmlns: null, /** - * @constructor + * Constructor: OpenLayers.Renderer.Elements * - * @param {String} containerID + * Parameters: + * containerID - {String} */ initialize: function(containerID) { OpenLayers.Renderer.prototype.initialize.apply(this, arguments); @@ -46,7 +58,7 @@ OpenLayers.Renderer.Elements.prototype = }, /** - * + * Method: destroy */ destroy: function() { @@ -60,8 +72,8 @@ OpenLayers.Renderer.Elements.prototype = }, /** + * Method: clear * Remove all the elements from the root - * @private */ clear: function() { if (this.root) { @@ -71,30 +83,33 @@ OpenLayers.Renderer.Elements.prototype = } }, - /** This function is in charge of asking the specific renderer which type - * of node to create for the given geometry. All geometries in an - * Elements-based renderer consist of one node and some attributes. We - * have the nodeFactory() function which creates a node for us, but it - * takes a 'type' as input, and that is precisely what this function - * tells us. + /** + * Method: getNodeType + * This function is in charge of asking the specific renderer which type + * of node to create for the given geometry. All geometries in an + * Elements-based renderer consist of one node and some attributes. We + * have the nodeFactory() function which creates a node for us, but it + * takes a 'type' as input, and that is precisely what this function + * tells us. + * + * Parameters: + * geometry - {} * - * @param geometry {OpenLayers.Geometry} - * - * @returns The corresponding node type for the specified geometry - * @type String - * @private + * Return: + * {String} The corresponding node type for the specified geometry */ getNodeType: function(geometry) { }, /** + * Method: drawGeometry * Draw the geometry, creating new nodes, setting paths, setting style, - * setting featureId on the node. This method should only be called - * by the renderer itself. + * setting featureId on the node. This method should only be called + * by the renderer itself. * - * @param {OpenLayers.Geometry} geometry - * @param {Object} style - * @param {String} featureId - * @private + * Parameters: + * geometry - {} + * style - {Object} + * featureId - {String} */ drawGeometry: function(geometry, style, featureId) { @@ -119,15 +134,16 @@ OpenLayers.Renderer.Elements.prototype = this.drawGeometryNode(node, geometry); }, - /** + /** + * Method: drawGeometryNode * Given a node, draw a geometry on the specified layer. - * node and geometry are required arguments, style is optional. - * This method is only called by the render itself. + * node and geometry are required arguments, style is optional. + * This method is only called by the render itself. * - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @param {Object} style - * @private + * Parameters: + * node - {DOMElement} + * geometry - {} + * style - {Object} */ drawGeometryNode: function(node, geometry, style) { style = style || node._style; @@ -168,43 +184,126 @@ OpenLayers.Renderer.Elements.prototype = this.setStyle(node, style, options, geometry); }, - /** - * virtual functions for drawing different Geometries. - * These should all be implemented by subclasses. - * These methods are only called by the render itself. - * - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawPoint + * Virtual function for drawing Point Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawPoint: function(node, geometry) {}, + + /** + * Method: drawLineString + * Virtual function for drawing LineString Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawLineString: function(node, geometry) {}, + + /** + * Method: drawLinearRing + * Virtual function for drawing LinearRing Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawLinearRing: function(node, geometry) {}, + + /** + * Method: drawPolygon + * Virtual function for drawing Polygon Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawPolygon: function(node, geometry) {}, + + /** + * Method: drawRectangle + * Virtual function for drawing Rectangle Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawRectangle: function(node, geometry) {}, + + /** + * Method: drawCircle + * Virtual function for drawing Circle Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawCircle: function(node, geometry) {}, + + /** + * Method: drawCurve + * Virtual function for drawing Curve Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawCurve: function(node, geometry) {}, + + /** + * Method: drawSurface + * Virtual function for drawing Surface Geometry. + * Should be implemented by subclasses. + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawSurface: function(node, geometry) {}, /** - * @param evt {Object} an OpenLayers.Event object + * Method: getFeatureIdFromEvent + * + * Parameters: + * evt - {Object} An object * - * @returns A geometry from an event that happened on a layer - * @type OpenLayers.Geometry - * @private + * Return: + * {} A geometry from an event that + * happened on a layer */ getFeatureIdFromEvent: function(evt) { var node = evt.target || evt.srcElement; return node._featureId; }, - /** Erase a geometry from the renderer. In the case of a multi-geometry, - * we cycle through and recurse on ourselves. Otherwise, we look for a - * node with the geometry.id, destroy its geometry, and remove it from - * the DOM. + /** + * Method: eraseGeometry + * Erase a geometry from the renderer. In the case of a multi-geometry, + * we cycle through and recurse on ourselves. Otherwise, we look for a + * node with the geometry.id, destroy its geometry, and remove it from + * the DOM. * - * @param {OpenLayers.Geometry} geometry - * @private + * Parameters: + * geometry - {} */ eraseGeometry: function(geometry) { if ((geometry.CLASS_NAME == "OpenLayers.Geometry.MultiPoint") || @@ -226,20 +325,19 @@ OpenLayers.Renderer.Elements.prototype = }, /** - * @private - * + * Method: nodeFactory * Create new node of the specified type, with the (optional) specified id. * * If node already exists with same ID and type, we remove it and then * call ourselves again to recreate it. * - * @param {String} id - * @param {String} type Kind of node to draw - * @param {OpenLayers.Geometry} geometry + * Parameters: + * id - {String} + * type - {String} type Kind of node to draw + * geometry - {} * - * @returns A new node of the given type and id - * @type DOMElement - * @private + * Return: + * {DOMElement} A new node of the given type and id */ nodeFactory: function(id, type, geometry) { var node = $(id); diff --git a/lib/OpenLayers/Renderer/SVG.js b/lib/OpenLayers/Renderer/SVG.js index b9fe9aa9d5..367ce20608 100644 --- a/lib/OpenLayers/Renderer/SVG.js +++ b/lib/OpenLayers/Renderer/SVG.js @@ -3,31 +3,43 @@ * for the full text of the license. */ /** - * @class - * * @requires OpenLayers/Renderer/Elements.js + * + * Class: OpenLayers.Renderer.SVG + * + * Inherits: + * - */ OpenLayers.Renderer.SVG = OpenLayers.Class.create(); OpenLayers.Renderer.SVG.prototype = OpenLayers.Class.inherit(OpenLayers.Renderer.Elements, { - /** @type String */ + /** + * Property: xmlns + * {String} + */ xmlns: "http://www.w3.org/2000/svg", - // Firefox has a limitation where values larger or smaller than about - // 15000 in an SVG document lock the browser up. This works around it. - /** @type Integer */ + /** + * Property: maxPixel + * {Integer} Firefox has a limitation where values larger or smaller than + * about 15000 in an SVG document lock the browser up. This + * works around it. + */ maxPixel: 15000, - /** @type Float - @private */ + /** + * Property: localResolution + * {Float} + */ localResolution: null, /** - * @constructor + * Constructor: OpenLayers.Renderer.SVN * - * @param {String} containerID + * Parameters: + * containerID - {String} */ initialize: function(containerID) { if (!this.supported()) { @@ -38,15 +50,17 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * + * APIMethod: destroy */ destroy: function() { OpenLayers.Renderer.Elements.prototype.destroy.apply(this, arguments); }, /** - * @returns Whether or not the browser supports the SVG renderer - * @type Boolean + * APIMethod: supported + * + * Return: + * {Boolean} Whether or not the browser supports the SVG renderer */ supported: function() { var svgFeature = "http://www.w3.org/TR/SVG11/feature#SVG"; @@ -57,8 +71,10 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * @param {OpenLayers.Bounds} extent - * @private + * Method: setExtent + * + * Parameters: + * extent - {} */ setExtent: function(extent) { OpenLayers.Renderer.Elements.prototype.setExtent.apply(this, @@ -97,12 +113,11 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * function - * - * sets the size of the drawing surface - * - * @param size {OpenLayers.Size} the size of the drawing surface - * @private + * Method: setSize + * Sets the size of the drawing surface. + * + * Parameters: + * size - {} The size of the drawing surface */ setSize: function(size) { OpenLayers.Renderer.prototype.setSize.apply(this, arguments); @@ -115,11 +130,13 @@ OpenLayers.Renderer.SVG.prototype = /** - * @param geometry {OpenLayers.Geometry} + * Method: getNodeType * - * @returns The corresponding node type for the specified geometry - * @type String - * @private + * Parameters: + * geometry - {} + * + * Return: + * {String} The corresponding node type for the specified geometry */ getNodeType: function(geometry) { var nodeType = null; @@ -148,17 +165,18 @@ OpenLayers.Renderer.SVG.prototype = }, /** + * Method: setStyle * Use to set all the style attributes to a SVG node. * - * Note: takes care to adjust stroke width and point radius - * to be resolution-relative + * Takes care to adjust stroke width and point radius to be + * resolution-relative * - * @param node {SVGDomElement} an SVG element to decorate - * @param {Object} style - * @param {Object} options - * @option isFilled {boolean} - * @option isStroked {boolean} - * @private + * Parameters: + * node - {SVGDomElement} An SVG element to decorate + * style - {Object} + * options - {Object} Currently supported options include + * 'isFilled' {Boolean} and + * 'isStroked' {Boolean} */ setStyle: function(node, style, options) { style = style || node._style; @@ -194,13 +212,14 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * @private - * - * @param {String} type Kind of node to draw - * @param {String} id Id for node + * Method: createNode * - * @returns A new node of the given type and id - * @type DOMElement + * Parameters: + * type - {String} Kind of node to draw + * id - {String} Id for node + * + * Return: + * {DOMElement} A new node of the given type and id */ createNode: function(type, id) { var node = document.createElementNS(this.xmlns, type); @@ -211,22 +230,24 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * @private - * - * @param {String} type Kind of node to draw - * @param {String} id Id for node + * Method: nodeTypeCompare * - * @returns Whether or not the specified node is of the specified type - * @type Boolean + * Parameters: + * node - {SVGDomElement} An SVG element + * type - {String} Kind of node + * + * Return: + * {Boolean} Whether or not the specified node is of the specified type */ nodeTypeCompare: function(node, type) { return (type == node.nodeName); }, /** - * @returns The specific render engine's root element - * @type DOMElement - * @private + * Method: createRenderRoot + * + * Return: + * {DOMElement} The specific render engine's root element */ createRenderRoot: function() { var id = this.container.id + "_svgRoot"; @@ -235,9 +256,10 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * @returns The main root element to which we'll add vectors - * @type DOMElement - * @private + * Method: createRoot + * + * Return: + * {DOMElement} The main root element to which we'll add vectors */ createRoot: function() { var id = this.container.id + "_root"; @@ -257,20 +279,26 @@ OpenLayers.Renderer.SVG.prototype = * * **************************************/ - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawPoint + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawPoint: function(node, geometry) { this.drawCircle(node, geometry, 1); }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @param {float} radius - * @private + /** + * Method: drawCircle + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + * radius - {Float} */ drawCircle: function(node, geometry, radius) { var resolution = this.getResolution(); @@ -290,29 +318,38 @@ OpenLayers.Renderer.SVG.prototype = }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawLineString + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawLineString: function(node, geometry) { node.setAttributeNS(null, "points", this.getComponentsString(geometry.components)); }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /**v + * Method: drawLinearRing + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawLinearRing: function(node, geometry) { node.setAttributeNS(null, "points", this.getComponentsString(geometry.components)); }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawPolygon + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawPolygon: function(node, geometry) { var d = ""; var draw = true; @@ -337,11 +374,14 @@ OpenLayers.Renderer.SVG.prototype = } }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawRectangle + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawRectangle: function(node, geometry) { // This needs to be reworked var x = (geometry.x / resolution + this.left); @@ -364,11 +404,14 @@ OpenLayers.Renderer.SVG.prototype = }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawCurve + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawCurve: function(node, geometry) { var d = null; var draw = true; @@ -394,11 +437,14 @@ OpenLayers.Renderer.SVG.prototype = } }, - /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private - */ + /** + * Method: drawSurface + * This method is only called by the renderer itself. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + */ drawSurface: function(node, geometry) { // create the svg path string representation @@ -428,8 +474,10 @@ OpenLayers.Renderer.SVG.prototype = }, /** - * @param {Array} components array of points - * @private + * Method: getComponentString + * + * Parameters: + * components - {Array} Array of points */ getComponentsString: function(components) { var strings = []; @@ -444,8 +492,13 @@ OpenLayers.Renderer.SVG.prototype = /** - * @param {OpenLayers.Geometry.Point} point - * @private + * Method: getShortString + * + * Parameters: + * point - {} + * + * Return: + * {String} */ getShortString: function(point) { var resolution = this.getResolution(); diff --git a/lib/OpenLayers/Renderer/VML.js b/lib/OpenLayers/Renderer/VML.js index 805ac0111a..0710a871c3 100644 --- a/lib/OpenLayers/Renderer/VML.js +++ b/lib/OpenLayers/Renderer/VML.js @@ -3,25 +3,35 @@ * for the full text of the license. */ /** - * @class + * @requires OpenLayers/Renderer/Elements.js + * + * Class: OpenLayers.Renderer.VML + * Render vector features in browsers with VML capability. Construct a new + * VML renderer with the constructor. * * Note that for all calculations in this class, we use toFixed() to round a * float value to an integer. This is done because it seems that VML doesn't * support float values. * - * @requires OpenLayers/Renderer/Elements.js + * Inherits from: + * - */ OpenLayers.Renderer.VML = OpenLayers.Class.create(); OpenLayers.Renderer.VML.prototype = OpenLayers.Class.inherit(OpenLayers.Renderer.Elements, { - /** @type String */ + /** + * Property: xmlns + * {String} XML Namespace URN + */ xmlns: "urn:schemas-microsoft-com:vml", /** - * @constructor - * - * @param {String} containerID + * Constructor: OpenLayers.Renderer.VML + * Create a new VML renderer. + * + * Parameters: + * containerID - {String} The id for the element that contains the renderer */ initialize: function(containerID) { if (!this.supported()) { @@ -36,15 +46,19 @@ OpenLayers.Renderer.VML.prototype = }, /** - * + * APIMethod: destroy + * Deconstruct the renderer. */ destroy: function() { OpenLayers.Renderer.Elements.prototype.destroy.apply(this, arguments); }, /** - * @returns Whether or not the browser supports the VML renderer - * @type Boolean + * APIMethod: supported + * Determine whether a browser supports this renderer. + * + * Return: + * {Boolean} The browser supports the VML renderer */ supported: function() { var supported = document.namespaces; @@ -52,7 +66,11 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @param {OpenLayers.Bounds} extent + * Method: setExtent + * Set the renderer's extent + * + * Parameters: + * extent - {} */ setExtent: function(extent) { OpenLayers.Renderer.Elements.prototype.setExtent.apply(this, @@ -70,9 +88,11 @@ OpenLayers.Renderer.VML.prototype = /** + * Method: setSize * Set the size of the drawing surface * - * @param size {OpenLayers.Size} the size of the drawing surface + * Parameters: + * size - {} the size of the drawing surface */ setSize: function(size) { OpenLayers.Renderer.prototype.setSize.apply(this, arguments); @@ -84,12 +104,15 @@ OpenLayers.Renderer.VML.prototype = this.root.style.height = "100%"; }, - /** - * @param geometry {OpenLayers.Geometry} - * - * @returns The corresponding node type for the specified geometry - * @type String - * @private + /** + * Method: getNodeType + * Get the noode type for a geometry + * + * Parameters: + * geometry - {} + * + * Return: + * {String} The corresponding node type for the specified geometry */ getNodeType: function(geometry) { var nodeType = null; @@ -114,15 +137,16 @@ OpenLayers.Renderer.VML.prototype = }, /** + * Method: setStyle * Use to set all the style attributes to a VML node. * - * @param {DOMElement} node - * @param {Object} style - * @param {Object} options - * @option isFilled {boolean} - * @option isStroked {boolean} - * @param {OpenLayers.Geometry} geometry - * @private + * Parameters: + * node - {DOMElement} + * style - {Object} + * options - {Object} + * isFilled - {Boolean} + * isStroked - {Boolean} + * geometry - {} */ setStyle: function(node, style, options, geometry) { style = style || node._style; @@ -175,12 +199,14 @@ OpenLayers.Renderer.VML.prototype = }, - /** Get the geometry's bounds, convert it to our vml coordinate system, - * then set the node's position, size, and local coordinate system. + /** + * Method: setNodeDimension + * Get the geometry's bounds, convert it to our vml coordinate system, + * then set the node's position, size, and local coordinate system. * - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Parameters: + * node - {DOMElement} + * geometry - {} */ setNodeDimension: function(node, geometry) { @@ -204,14 +230,16 @@ OpenLayers.Renderer.VML.prototype = node.coordsize = scaledBox.getWidth()+ " " + scaledBox.getHeight(); }, - /** - * @private + /** + * Method: createNode + * Create a new node * - * @param {String} type Kind of node to draw - * @param {String} id Id for node - * - * @returns A new node of the given type and id - * @type DOMElement + * Parameters: + * type - {String} Kind of node to draw + * id - {String} Id for node + * + * Return: + * {DOMElement} A new node of the given type and id */ createNode: function(type, id) { var node = document.createElement(type); @@ -221,14 +249,16 @@ OpenLayers.Renderer.VML.prototype = return node; }, - /** - * @private + /** + * Method: nodeTypeCompare + * Determine whether a node is of a given type * - * @param {String} type Kind of node to draw - * @param {String} id Id for node - * - * @returns Whether or not the specified node is of the specified type - * @type Boolean + * Parameters: + * type - {String} Kind of node to draw + * id - {String} Id for node + * + * Return: + * {Boolean} Whether or not the specified node is of the specified type */ nodeTypeCompare: function(node, type) { @@ -250,9 +280,11 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @returns The specific render engine's root element - * @type DOMElement - * @private + * Method: createRenderRoot + * Create the renderer root + * + * Return: + * {DOMElement} The specific render engine's root element */ createRenderRoot: function() { var id = this.container.id + "_vmlRoot"; @@ -261,9 +293,11 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @returns The main root element to which we'll add vectors - * @type DOMElement - * @private + * Method: createRoot + * Create the main root element + * + * Return: + * {DOMElement} The main root element to which we'll add vectors */ createRoot: function() { var id = this.container.id + "_root"; @@ -278,20 +312,26 @@ OpenLayers.Renderer.VML.prototype = **************************************/ /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawPoint + * Render a point + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawPoint: function(node, geometry) { this.drawCircle(node, geometry, 1); }, - /** Size and Center a circle given geometry (x,y center) and radius + /** + * Method: drawCircle + * Render a circle. + * Size and Center a circle given geometry (x,y center) and radius * - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @param {float} radius - * @private + * Parameters: + * node - {DOMElement} + * geometry - {} + * radius - {float} */ drawCircle: function(node, geometry, radius) { @@ -308,28 +348,37 @@ OpenLayers.Renderer.VML.prototype = /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawLineString + * Render a linestring. + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawLineString: function(node, geometry) { this.drawLine(node, geometry, false); }, /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawLinearRing + * Render a linearring + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawLinearRing: function(node, geometry) { this.drawLine(node, geometry, true); }, /** - * @param {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @param {Boolean} closeLine Close the line? (make it a ring?) - * @private + * Method: DrawLine + * Render a line. + * + * Parameters: + * node - {DOMElement} + * geometry - {} + * closeLine - {Boolean} Close the line? (make it a ring?) */ drawLine: function(node, geometry, closeLine) { @@ -352,9 +401,12 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @parm {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawPolygon + * Render a polygon + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawPolygon: function(node, geometry) { this.setNodeDimension(node, geometry); @@ -381,9 +433,12 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @parm {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawRectangle + * Render a rectangle + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawRectangle: function(node, geometry) { var resolution = this.getResolution(); @@ -397,9 +452,11 @@ OpenLayers.Renderer.VML.prototype = /** - * @parm {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawCurve + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawCurve: function(node, geometry) { this.setNodeDimension(node, geometry); @@ -424,9 +481,11 @@ OpenLayers.Renderer.VML.prototype = }, /** - * @parm {DOMElement} node - * @param {OpenLayers.Geometry} geometry - * @private + * Method: drawSurface + * + * Parameters: + * node - {DOMElement} + * geometry - {} */ drawSurface: function(node, geometry) { @@ -450,5 +509,6 @@ OpenLayers.Renderer.VML.prototype = node.path = path; }, + /** @final @type String*/ CLASS_NAME: "OpenLayers.Renderer.VML" }); diff --git a/lib/OpenLayers/SingleFile.js b/lib/OpenLayers/SingleFile.js index 8d49452524..5b3581ffdd 100644 --- a/lib/OpenLayers/SingleFile.js +++ b/lib/OpenLayers/SingleFile.js @@ -2,5 +2,8 @@ * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt * for the full text of the license. */ -_OPENLAYERS_SFL_=true; +OpenLayers = { + singleFile: true +}; + diff --git a/lib/OpenLayers/Tile.js b/lib/OpenLayers/Tile.js index 5dbb729fe5..29e2346e76 100644 --- a/lib/OpenLayers/Tile.js +++ b/lib/OpenLayers/Tile.js @@ -4,14 +4,15 @@ /* - * @class * @requires OpenLayers/Util.js - * + * + * Class: OpenLayers.Tile * This is a class designed to designate a single tile, however * it is explicitly designed to do relatively little. Tiles store information * about themselves -- such as the URL that they are related to, and their * size - but do not add themselves to the layer div automatically, for - * example. + * example. Create a new tile with the constructor, or + * a subclass. * * TBD 3.0 - remove reference to url in above paragraph * @@ -19,43 +20,65 @@ OpenLayers.Tile = OpenLayers.Class.create(); OpenLayers.Tile.prototype = { - /** @type String */ - id: null, + /** + * Property: id + * {String} null + */ + id: null, - /** @type OpenLayers.Layer */ - layer: null, + /** + * Property: layer + * {} layer the tile is attached to + */ + layer: null, - /** TBD 3.0 - * @deprecated The base tile class does not need an url. This should be - * handled in subclasses. Does not belong here. - * - * @type String url of the request */ - url:null, + /** + * Property: url + * {String} url of the request + * + * TBD 3.0 + * Deprecated. The base tile class does not need an url. This should be + * handled in subclasses. Does not belong here. + */ + url: null, - /** @type OpenLayers.Bounds */ - bounds:null, + /** + * APIProperty: bounds + * {} null + */ + bounds: null, - /** @type OpenLayers.Size */ - size:null, + /** + * Property: size + * {} null + */ + size: null, - /** Top Left pixel of the tile - * @type OpenLayers.Pixel */ - position:null, + /** + * Property: position + * {} Top Left pixel of the tile + */ + position: null, - /** @type Boolean */ - drawn: false, + /** + * Property: drawn + * {Boolean} false + */ + drawn: false, /** TBD 3.0 -- remove 'url' from the list of parameters to the constructor. * there is no need for the base tile class to have a url. * - * @constructor - * - * @param {OpenLayers.Layer} layer - * @param {OpenLayers.Pixel} position - * @param {OpenLayers.Bounds} bounds - * @param {String} url - * @param {OpenLayers.Size} size - */ + * Constructor: OpenLayers.Tile + * Constructor for a new instance. + * + * Parameters: + * layer - {} layer that the tile will go in. + * position - {} + * bounds - {} + * url - {} + * size - {} + */ initialize: function(layer, position, bounds, url, size) { this.layer = layer; this.position = position; @@ -67,8 +90,10 @@ OpenLayers.Tile.prototype = { this.id = OpenLayers.Util.createUniqueID("Tile_"); }, - /** nullify references to prevent circular references and memory leaks - */ + /** + * APIMethod: destroy + * nullify references to prevent circular references and memory leaks + */ destroy:function() { this.layer = null; this.bounds = null; @@ -77,14 +102,15 @@ OpenLayers.Tile.prototype = { }, /** + * Method: draw * Clear whatever is currently in the tile, then return whether or not * it should actually be re-drawn. * - * @returns Whether or not the tile should actually be drawn. Note that + * Return: + * {Boolean} Whether or not the tile should actually be drawn. Note that * this is not really the best way of doing things, but such is * the way the code has been developed. Subclasses call this and * depend on the return to know if they should draw or not. - * @type Boolean */ draw: function() { @@ -112,10 +138,13 @@ OpenLayers.Tile.prototype = { }, /** - * @param {OpenLayers.Bounds} - * @param {OpenLayers.pixel} position - * @param {Boolean} redraw Redraw tile after moving? - * Default is true + * Method: moveTo + * Reposition the tile. + * + * Parameters: + * bounds - {} + * position - {} + * redraw - {Boolean} Call draw method on tile after moving? Default is true */ moveTo: function (bounds, position, redraw) { if (redraw == null) { @@ -130,13 +159,27 @@ OpenLayers.Tile.prototype = { } }, - /** Clear the tile of any bounds/position-related data so that it can - * be reused in a new location. + /** + * Method: clear + * Clear the tile of any bounds/position-related data so that it can + * be reused in a new location. */ clear: function() { this.drawn = false; }, + /** + * Method: getBoundsFromBaseLayer + * Take the pixel locations of the corner of the tile, and pass them to the base layer + * and ask for the location of those pixels, so that displaying tiles over Google + * works fine. + * + * Parameters: + * position - {} + * + * Return: + * bounds - {} + */ getBoundsFromBaseLayer: function(position) { var topLeft = this.layer.map.getLonLatFromLayerPx(position); var bottomRightPx = position.clone(); @@ -159,5 +202,3 @@ OpenLayers.Tile.prototype = { /** @final @type String */ CLASS_NAME: "OpenLayers.Tile" }; - - diff --git a/lib/OpenLayers/Tile/Image.js b/lib/OpenLayers/Tile/Image.js index d930a3e0a9..89d5f97798 100644 --- a/lib/OpenLayers/Tile/Image.js +++ b/lib/OpenLayers/Tile/Image.js @@ -4,39 +4,54 @@ /** - * @class - * * @requires OpenLayers/Tile.js + * + * Class: OpenLayers.Tile.Image + * Instances of OpenLayers.Tile.Image are used to manage the image tiles + * used by various layers. Create a new image tile with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Tile.Image = OpenLayers.Class.create(); OpenLayers.Tile.Image.prototype = OpenLayers.Class.inherit( OpenLayers.Tile, { - /** @type String */ + /** + * Property: url + * {String} The URL of the image being requested. No default. Filled in by + * layer.getURL() function. + */ url: null, - /** @type DOMElement img */ + /** + * Property: imgDiv + * {DOMElement} The div element which wraps the image. + */ imgDiv: null, /** - * The image element is appended to the frame. Any gutter on the image - * will be hidden behind the frame. - * - * @type DOMElement div */ + * Property: frame + * {DOMElement} The image element is appended to the frame. Any gutter on + * the image will be hidden behind the frame. + */ frame: null, /** TBD 3.0 - reorder the parameters to the init function to put URL * as last, so we can continue to call tile.initialize() * without changing the arguments. * - * @constructor - * - * @param {OpenLayers.Grid} layer - * @param {OpenLayers.Pixel} position - * @param {OpenLayers.Bounds} bounds - * @param {String} url - * @param {OpenLayers.Size} size - */ + * Constructor: OpenLayers.Tile.Image + * Constructor for a new instance. + * + * Parameters: + * layer - {} layer that the tile will go in. + * position - {} + * bounds - {} + * url - {} + * size - {} + */ initialize: function(layer, position, bounds, url, size) { OpenLayers.Tile.prototype.initialize.apply(this, arguments); @@ -47,8 +62,9 @@ OpenLayers.Tile.Image.prototype = this.frame.style.position = 'absolute'; }, - /** - * + /** + * APIMethod: destroy + * nullify references to prevent circular references and memory leaks */ destroy: function() { if (this.imgDiv != null) { @@ -67,7 +83,11 @@ OpenLayers.Tile.Image.prototype = }, /** + * Method: draw + * Check that a tile should be drawn, and draw it. * + * Return: + * {Boolean} Always returns true. */ draw:function() { if (this.layer != this.layer.map.baseLayer && this.layer.reproject) { @@ -99,7 +119,9 @@ OpenLayers.Tile.Image.prototype = return true; }, - /** Clear the tile of any bounds/position-related data so that it can + /** + * Method: clear + * Clear the tile of any bounds/position-related data so that it can * be reused in a new location. */ clear: function() { @@ -110,9 +132,13 @@ OpenLayers.Tile.Image.prototype = }, /** - * @param {OpenLayers.Bounds} - * @param {OpenLayers.pixel} position - * @param {Boolean} redraw + * Method: moveTo + * Reposition the tile. + * + * Parameters: + * bounds - {} + * position - {} + * redraw - {Boolean} Call draw method on tile after moving? Default is true */ moveTo: function (bounds, position, redraw) { if (this.layer != this.layer.map.baseLayer && this.layer.reproject) { @@ -123,7 +149,8 @@ OpenLayers.Tile.Image.prototype = }, /** - * + * Method: initImgDiv + * Creates the imgDiv property on the tile. */ initImgDiv: function() { if (this.layer.alpha) { @@ -173,6 +200,7 @@ OpenLayers.Tile.Image.prototype = }, /** + * Method: checkImgURL * Make sure that the image that just loaded is the one this tile is meant * to display, since panning/zooming might have changed the tile's URL in * the meantime. If the tile URL did change before the image loaded, set @@ -187,8 +215,6 @@ OpenLayers.Tile.Image.prototype = * * See discussion in the thread at * http://openlayers.org/pipermail/dev/2007-January/000205.html - * - * @private */ checkImgURL: function () { // Sometimes our image will load after it has already been removed @@ -201,7 +227,10 @@ OpenLayers.Tile.Image.prototype = } }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Tile.Image" } ); diff --git a/lib/OpenLayers/Tile/WFS.js b/lib/OpenLayers/Tile/WFS.js index 6406a48814..5dd1965158 100644 --- a/lib/OpenLayers/Tile/WFS.js +++ b/lib/OpenLayers/Tile/WFS.js @@ -4,40 +4,55 @@ /** - * @class - * * @requires OpenLayers/Tile.js + * + * Class: OpenLayers.Tile.WFS + * Instances of OpenLayers.Tile.WFS are used to manage the image tiles + * used by various layers. Create a new image tile with the + * constructor. + * + * Inherits from: + * - */ OpenLayers.Tile.WFS = OpenLayers.Class.create(); OpenLayers.Tile.WFS.prototype = OpenLayers.Class.inherit( OpenLayers.Tile, { - /** @type Array(OpenLayers.Feature)*/ - features: null, + /** + * Property: features + * {Array()} list of features in this tile + */ + features: null, - /** @type Array(String) */ - url: null, + /** + * Property: url + * {String} + */ + url: null, /** TBD 3.0 - reorder the parameters to the init function to put URL * as last, so we can continue to call tile.initialize() * without changing the arguments. * - * @constructor - * - * @param {OpenLayers.Layer} layer - * @param {OpenLayers.Pixel} position - * @param {OpenLayers.Bounds} bounds - * @param {String} url - * @param {OpenLayers.Size} size - */ + * Constructor: OpenLayers.Tile.WFS + * Constructor for a new instance. + * + * Parameters: + * layer - {} layer that the tile will go in. + * position - {} + * bounds - {} + * url - {} + * size - {} + */ initialize: function(layer, position, bounds, url, size) { OpenLayers.Tile.prototype.initialize.apply(this, arguments); this.url = url; this.features = new Array(); }, - /** - * + /** + * APIMethod: destroy + * nullify references to prevent circular references and memory leaks */ destroy: function() { OpenLayers.Tile.prototype.destroy.apply(this, arguments); @@ -46,7 +61,9 @@ OpenLayers.Tile.WFS.prototype = this.url = null; }, - /** Clear the tile of any bounds/position-related data so that it can + /** + * Method: clear + * Clear the tile of any bounds/position-related data so that it can * be reused in a new location. */ clear: function() { @@ -55,7 +72,8 @@ OpenLayers.Tile.WFS.prototype = }, /** - * + * Method: draw + * Check that a tile should be drawn, and load features for it. */ draw:function() { if (OpenLayers.Tile.prototype.draw.apply(this, arguments)) { @@ -63,21 +81,28 @@ OpenLayers.Tile.WFS.prototype = } }, - /** get the full request string from the ds and the tile params + /** + * Method: loadFeaturesForRegion + * get the full request string from the ds and the tile params * and call the AJAX loadURL(). * - * input are function pointers for what to do on success and failure. - * - * @param {function} success - * @param {function} failure + * Input are function pointers for what to do on success and failure. + * + * Parameters: + * success - {function} + * failure - {function} */ loadFeaturesForRegion:function(success, failure) { OpenLayers.loadURL(this.url, null, this, success); }, - /** Return from AJAX request + /** + * Method: requestSuccess + * Called on return from request succcess. Adds results via + * layer.addFeatures in vector mode, addResults otherwise. * - * @param {} request + * Parameters: + * request - {XMLHttpRequest} */ requestSuccess:function(request) { var doc = request.responseXML; @@ -95,7 +120,12 @@ OpenLayers.Tile.WFS.prototype = }, /** - * @param {Object} results + * Method: addResults + * Construct new feature via layer featureClass constructor, and add to + * this.features. + * + * Parameters: + * results - {Object} */ addResults: function(results) { for (var i=0; i < results.length; i++) { @@ -106,10 +136,10 @@ OpenLayers.Tile.WFS.prototype = }, - /** Iterate through and call destroy() on each feature, removing it from + /** + * Method: destroyAllFeatures + * Iterate through and call destroy() on each feature, removing it from * the local array - * - * @private */ destroyAllFeatures: function() { while(this.features.length > 0) { @@ -118,7 +148,10 @@ OpenLayers.Tile.WFS.prototype = } }, - /** @final @type String */ + /** + * Constant: CLASS_NAME + * {String} Name of class. + */ CLASS_NAME: "OpenLayers.Tile.WFS" } ); diff --git a/lib/OpenLayers/Util.js b/lib/OpenLayers/Util.js index 46d38f0fca..24b4e47c72 100644 --- a/lib/OpenLayers/Util.js +++ b/lib/OpenLayers/Util.js @@ -4,11 +4,12 @@ /** - * @class + * Namespace: Util */ OpenLayers.Util = new Object(); /** + * Function: getElement * This is the old $() from prototype */ OpenLayers.Util.getElement = function() { @@ -34,7 +35,10 @@ if ($ == null) { var $ = OpenLayers.Util.getElement; } -/* from Prototype.js */ +/** + * Function: extend + * From Prototype.js + */ OpenLayers.Util.extend = function(destination, source) { for (property in source) { destination[property] = source[property]; @@ -43,14 +47,18 @@ OpenLayers.Util.extend = function(destination, source) { }; -/** Remove an object from an array. Iterates through the array -* to find the item, then removes it. -* -* @param {Object} item -* -* @returns A reference to the array -* @type Array -*/ +/** + * Function: removeItem + * Remove an object from an array. Iterates through the array + * to find the item, then removes it. + * + * Parameters: + * array - {Array} + * item - {Object} + * + * Return + * {Array} A reference to the array + */ OpenLayers.Util.removeItem = function(array, item) { for(var i=0; i < array.length; i++) { if(array[i] == item) { @@ -62,15 +70,23 @@ OpenLayers.Util.removeItem = function(array, item) { }; /** + * Function: clearArray */ OpenLayers.Util.clearArray = function(array) { array.length = 0; }; -/** Seems to exist already in FF, but not in MOZ. +/** + * Function: indexOf + * Seems to exist already in FF, but not in MOZ. * - * @param {Array} array - * @param {Object} obj + * Parameters: + * array - {Array} + * obj - {Object} + * + * Returns: + * {Integer} The index at, which the object was found in the array. + * If not found, returns -1.v */ OpenLayers.Util.indexOf = function(array, obj) { @@ -83,13 +99,16 @@ OpenLayers.Util.indexOf = function(array, obj) { /** - * @param {String} id - * @param {OpenLayers.Pixel} px - * @param {OpenLayers.Size} sz - * @param {String} position - * @param {String} border - * @param {String} overflow - * @param {float} opacity Fractional value (0.0 - 1.0) + * Function: modifyDOMElement + * + * Parameters: + * id - {String} + * px - {} + * sz - {} + * position - {String} + * border - {String} + * overflow - {String} + * opacity - {Float} Fractional value (0.0 - 1.0) */ OpenLayers.Util.modifyDOMElement = function(element, id, px, sz, position, border, overflow, opacity) { @@ -121,20 +140,23 @@ OpenLayers.Util.modifyDOMElement = function(element, id, px, sz, position, }; /** -* zIndex is NOT set -* -* @param {String} id -* @param {OpenLayers.Pixel} px -* @param {OpenLayers.Size} sz -* @param {String} imgURL -* @param {String} position -* @param {String} border -* @param {String} overflow -* @param {float} opacity Fractional value (0.0 - 1.0) -* -* @returns A DOM Div created with the specified attributes. -* @type DOMElement -*/ + * Function: createDiv + * + * Note: zIndex is NOT set + * + * Parameters: + * id - {String} + * px - {} + * sz - {} + * imgURL - {String} + * position - {String} + * border - {String} + * overflow - {String} + * opacity - {Float} Fractional value (0.0 - 1.0) + * + * Return: + * {DOMElement} A DOM Div created with the specified attributes. + */ OpenLayers.Util.createDiv = function(id, px, sz, imgURL, position, border, overflow, opacity) { @@ -157,19 +179,22 @@ OpenLayers.Util.createDiv = function(id, px, sz, imgURL, position, return dom; }; -/** -* @param {String} id -* @param {OpenLayers.Pixel} px -* @param {OpenLayers.Size} sz -* @param {String} imgURL -* @param {String} position -* @param {String} border -* @param {Boolean} delayDisplay -* @param {float} opacity Fractional value (0.0 - 1.0) -* -* @returns A DOM Image created with the specified attributes. -* @type DOMElement -*/ +/** + * Function: createImage + * + * Parameters: + * id - {String} + * px - {} + * sz - {} + * imgURL - {String} + * position - {String} + * border - {String} + * delayDisplay - {Boolean} + * opacity - {Float} Fractional value (0.0 - 1.0) + * + * Return: + * {DOMElement} A DOM Image created with the specified attributes. + */ OpenLayers.Util.createImage = function(id, px, sz, imgURL, position, border, opacity, delayDisplay) { @@ -207,22 +232,30 @@ OpenLayers.Util.createImage = function(id, px, sz, imgURL, position, border, }; /** - * @deprecated -- Use OpenLayers.Util.modifyDOMElement() or - * OpenLayers.Util.modifyAlphaImageDiv() + * Function: setOpacity + * Deprecated. + * This function has been deprecated. Instead, please use + * OpenLayers.Util.modifyDOMElement() + * or + * OpenLayers.Util.modifyAlphaImageDiv() * * Set the opacity of a DOM Element - * Note that for this function to work in IE, elements must "have layout" - * according to: - * http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/haslayout.asp + * Note that for this function to work in IE, elements must "have layout" + * according to: + * http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/haslayout.asp * - * @param {DOMElement} element Set the opacity on this DOM element - * @param {Float} opacity Opacity value (0.0 - 1.0) + * Parameters: + * element - {DOMElement} Set the opacity on this DOM element + * opacity - {Float} Opacity value (0.0 - 1.0) */ OpenLayers.Util.setOpacity = function(element, opacity) { OpenLayers.Util.modifyDOMElement(element, null, null, null, null, null, null, opacity); } +/** + * Function: onImageLoad + */ OpenLayers.Util.onImageLoad = function() { // The complex check here is to solve issues described in #480. // Every time a map view changes, it increments the 'viewRequestID' @@ -245,8 +278,23 @@ OpenLayers.Util.onImageLoad = function() { } }; +/** + * Property: onImageLoadErrorColor + * {String} The color tiles with load errors will turn. + * Default is "pink" + */ OpenLayers.Util.onImageLoadErrorColor = "pink"; + +/** + * Property: onImageLoadErrorColor + * {Integer} How many times should we try to reload an image before giving up? + * Default is 0 + */ OpenLayers.IMAGE_RELOAD_ATTEMPTS = 0; + +/** + * Function: onImageLoadError + */ OpenLayers.Util.onImageLoadError = function() { this._attempts = (this._attempts) ? (this._attempts + 1) : 1; if(this._attempts <= OpenLayers.IMAGE_RELOAD_ATTEMPTS) { @@ -257,7 +305,12 @@ OpenLayers.Util.onImageLoadError = function() { this.style.display = ""; }; - +/** + * Function: alphaHack + * + * Return: + * {Boolean} + */ OpenLayers.Util.alphaHack = function() { var arVersion = navigator.appVersion.split("MSIE"); var version = parseFloat(arVersion[1]); @@ -278,16 +331,18 @@ OpenLayers.Util.alphaHack = function() { } /** -* @param {DOMElement} div Div containing Alpha-adjusted Image -* @param {String} id -* @param {OpenLayers.Pixel} px -* @param {OpenLayers.Size} sz -* @param {String} imgURL -* @param {String} position -* @param {String} border -* @param {String} sizing 'crop', 'scale', or 'image'. Default is "scale" -* @param {float} opacity Specified as fraction (0.4, etc) -*/ + * Function: modifyAlphaImageDiv + * + * div - {DOMElement} Div containing Alpha-adjusted Image + * id - {String} + * px - {} + * sz - {} + * imgURL - {String} + * position - {String} + * border - {String} + * sizing {String} 'crop', 'scale', or 'image'. Default is "scale" + * opacity - {Float} Fractional value (0.0 - 1.0) + */ OpenLayers.Util.modifyAlphaImageDiv = function(div, id, px, sz, imgURL, position, border, sizing, opacity) { @@ -326,19 +381,21 @@ OpenLayers.Util.modifyAlphaImageDiv = function(div, id, px, sz, imgURL, }; /** -* @param {String} id -* @param {OpenLayers.Pixel} px -* @param {OpenLayers.Size} sz -* @param {String} imgURL -* @param {String} position -* @param {String} border -* @param {String} sizing 'crop', 'scale', or 'image'. Default is "scale" -* @param {Boolean} delayDisplay -* -* @returns A DOM Div created with a DOM Image inside it. If the hack is -* needed for transparency in IE, it is added. -* @type DOMElement -*/ + * Function: createAlphaImageDiv + * + * id - {String} + * px - {} + * sz - {} + * imgURL - {String} + * position - {String} + * border - {String} + * sizing {String} 'crop', 'scale', or 'image'. Default is "scale" + * delayDisplay{Boolean} + * + * Return: + * {DOMElement} A DOM Div created with a DOM Image inside it. If the hack is + * needed for transparency in IE, it is added. + */ OpenLayers.Util.createAlphaImageDiv = function(id, px, sz, imgURL, position, border, sizing, opacity, delayDisplay) { @@ -363,15 +420,18 @@ OpenLayers.Util.createAlphaImageDiv = function(id, px, sz, imgURL, }; -/** Creates a new hashtable and copies over all the keys from the -* passed-in object, but storing them under an uppercased -* version of the key at which they were stored. -* -* @param {Object} object -* -* @returns A new Object with all the same keys but uppercased -* @type Object -*/ +/** + * Function: upperCaseObject + * Creates a new hashtable and copies over all the keys from the + * passed-in object, but storing them under an uppercased + * version of the key at which they were stored. + * + * Parameters: + * object - {Object} + * + * Returns: + * {Object} A new Object with all the same keys but uppercased + */ OpenLayers.Util.upperCaseObject = function (object) { var uObject = new Object(); for (var key in object) { @@ -380,13 +440,16 @@ OpenLayers.Util.upperCaseObject = function (object) { return uObject; }; -/** Takes a hashtable and copies any keys that don't exist from -* another hashtable, by analogy with OpenLayers.Util.extend() from -* Prototype.js. -* -* @param {Object} to -* @param {Object} from -*/ +/** + * Function: applyDefaults + * Takes a hashtable and copies any keys that don't exist from + * another hashtable, by analogy with OpenLayers.Util.extend() from + * Prototype.js. + * + * Parameters: + * to - {Object} + * from - {Object} + */ OpenLayers.Util.applyDefaults = function (to, from) { for (var key in from) { if (to[key] == null) { @@ -396,16 +459,19 @@ OpenLayers.Util.applyDefaults = function (to, from) { }; /** -* @param {Object} params -* -* @returns a concatenation of the properties of an object in -* http parameter notation. -* (ex. "key1=value1&key2=value2&key3=value3") -* If a parameter is actually a list, that parameter will then -* be set to a comma-seperated list of values (foo,bar) instead -* of being URL escaped (foo%3Abar). -* @type String -*/ + * Function: getParameterString + * + * Parameters: + * params - {Object} + * + * Return: + * {String} A concatenation of the properties of an object in + * http parameter notation. + * (ex. "key1=value1&key2=value2&key3=value3") + * If a parameter is actually a list, that parameter will then + * be set to a comma-seperated list of values (foo,bar) instead + * of being URL escaped (foo%3Abar). + */ OpenLayers.Util.getParameterString = function(params) { paramsArray = new Array(); @@ -432,18 +498,27 @@ OpenLayers.Util.getParameterString = function(params) { return paramsArray.join("&"); }; -/** -* @returns The fully formatted image location string -* @type String -*/ - +/** + * Property: ImgPath + * {String} Default is ''. + */ OpenLayers.ImgPath = ''; + +/** + * Function: getImagesLocation + * + * Return: + * {String} The fully formatted image location string + */ OpenLayers.Util.getImagesLocation = function() { return OpenLayers.ImgPath || (OpenLayers._getScriptLocation() + "img/"); }; -/* Originally from Prototype */ +/** + * Function: Try + * + */ OpenLayers.Util.Try = function() { var returnValue; @@ -459,13 +534,18 @@ OpenLayers.Util.Try = function() { } -/** These could/should be made namespace aware? -* -* @param {} p -* @param {str} tagName -* -* @return {Array} -*/ +/** + * Function: getNodes + * + * These could/should be made namespace aware? + * + * Parameters: + * p - {} + * tagName - {String} + * + * Return: + * {Array} + */ OpenLayers.Util.getNodes=function(p, tagName) { var nodes = OpenLayers.Util.Try( function () { @@ -480,11 +560,15 @@ OpenLayers.Util.getNodes=function(p, tagName) { }; /** -* @param {Array} nodes -* @param {str} tagName -* -* @return {Array} -*/ + * Function: _getNodes + * + * Parameters: + * nodes - {Array} + * tagName - {String} + * + * Return: + * {Array} + */ OpenLayers.Util._getNodes=function(nodes, tagName) { var retArray = new Array(); for (var i=0;i 0)) @@ -524,10 +612,13 @@ OpenLayers.Util.getTagText = function (parent, item, index) { }; /** - * @param {XMLNode} node + * Function: getXmlNodeValue * - * @returns The text value of the given node, without breaking in firefox or IE - * @type String + * Parameters: + * node - {XMLNode} + * + * Return: + * {String} The text value of the given node, without breaking in firefox or IE */ OpenLayers.Util.getXmlNodeValue = function(node) { var val = null; @@ -546,11 +637,15 @@ OpenLayers.Util.getXmlNodeValue = function(node) { }; /** -* @param {Event} evt -* @param {HTMLDivElement} div -* -* @return {boolean} -*/ + * Function: mouseLeft + * + * Parameters: + * evt - {Event} + * div - {HTMLDivElement} + * + * Return: + * {Boolean} + */ OpenLayers.Util.mouseLeft = function (evt, div) { // start with the element to which the mouse has moved var target = (evt.relatedTarget) ? evt.relatedTarget : evt.toElement; @@ -562,7 +657,27 @@ OpenLayers.Util.mouseLeft = function (evt, div) { return (target != div); }; +/** + * Function: rad + * + * Parameters: + * x - {Float} + * + * Return: + * {Float} + */ OpenLayers.Util.rad = function(x) {return x*Math.PI/180;}; + +/** + * Function: distVincenty + * + * Parameters: + * p1 - {Float} + * p2 - {Float} + * + * Return: + * {Float} + */ OpenLayers.Util.distVincenty=function(p1, p2) { var a = 6378137, b = 6356752.3142, f = 1/298.257223563; var L = OpenLayers.Util.rad(p2.lon - p1.lon); @@ -599,11 +714,14 @@ OpenLayers.Util.distVincenty=function(p1, p2) { }; /** - * @param {String} url Optional url used to extract the query string. - * If null, query string is taken from page location. + * Function: getArgs * - * @returns An object of key/value pairs from the query string. - * @type Object + * Parameters: + * url - {String} Optional url used to extract the query string. + * If null, query string is taken from page location. + * + * Return: + * {Object} An object of key/value pairs from the query string. */ OpenLayers.Util.getArgs = function(url) { if(url == null) { @@ -638,14 +756,22 @@ OpenLayers.Util.getArgs = function(url) { return args; } +/** + * Property: lastSeqID + * {Integer} The ever-incrementing count variable. + * Used for generating unique ids. + */ OpenLayers.Util.lastSeqID = 0; /** - * @param {String} prefix String to prefix random id. If null, default - * is "id_" + * Function: createUniqueID * - * @returns A unique id string, built on the passed in prefix - * @type String + * Parameters: + * prefix {String} String to prefix random id. + * If null, default is "id_" + * + * Return: + * {String} A unique id string, built on the passed in prefix */ OpenLayers.Util.createUniqueID = function(prefix) { if (prefix == null) { @@ -655,10 +781,10 @@ OpenLayers.Util.createUniqueID = function(prefix) { return prefix + OpenLayers.Util.lastSeqID; }; -/** Constant inches per unit - * -- borrowed from MapServer mapscale.c - * - * @type Object */ +/** + * Constant: INCHES_PER_UNIT + * {Object} Constant inches per unit -- borrowed from MapServer mapscale.c + */ OpenLayers.INCHES_PER_UNIT = { 'inches': 1.0, 'ft': 12.0, @@ -670,18 +796,23 @@ OpenLayers.INCHES_PER_UNIT = { OpenLayers.INCHES_PER_UNIT["in"]= OpenLayers.INCHES_PER_UNIT.inches; OpenLayers.INCHES_PER_UNIT["degrees"] = OpenLayers.INCHES_PER_UNIT.dd; -/** A sensible default - * @type int */ +/** + * Constant: DOTS_PER_INCH + * {Integer} 72 (A sensible default) + */ OpenLayers.DOTS_PER_INCH = 72; /** - * @param {float} scale + * Function: normalzeScale * - * @returns A normalized scale value, in 1 / X format. - * This means that if a value less than one ( already 1/x) is passed - * in, it just returns scale directly. Otherwise, it returns - * 1 / scale - * @type float + * Parameters: + * scale {float} + * + * Return: + * {Float} A normalized scale value, in 1 / X format. + * This means that if a value less than one ( already 1/x) is passed + * in, it just returns scale directly. Otherwise, it returns + * 1 / scale */ OpenLayers.Util.normalizeScale = function (scale) { var normScale = (scale > 1.0) ? (1.0 / scale) @@ -690,13 +821,16 @@ OpenLayers.Util.normalizeScale = function (scale) { }; /** - * @param {float} scale - * @param {String} units Index into OpenLayers.INCHES_PER_UNIT hashtable. - * Default is degrees + * Function: getResolutionFromScale * - * @returns The corresponding resolution given passed-in scale and unit - * parameters. - * @type float + * Parameters: + * scale - {Float} + * units - {String} Index into OpenLayers.INCHES_PER_UNIT hashtable. + * Default is degrees + * + * Return: + * {Float} The corresponding resolution given passed-in scale and unit + * parameters. */ OpenLayers.Util.getResolutionFromScale = function (scale, units) { @@ -712,13 +846,16 @@ OpenLayers.Util.getResolutionFromScale = function (scale, units) { }; /** - * @param {float} resolution - * @param {String} units Index into OpenLayers.INCHES_PER_UNIT hashtable. - * Default is degrees + * Function: getScaleFromResolution * - * @returns The corresponding scale given passed-in resolution and unit - * parameters. - * @type float + * Parameters: + * resolution - {Float} + * units - {String} Index into OpenLayers.INCHES_PER_UNIT hashtable. + * Default is degrees + * + * Return: + * {Float} The corresponding scale given passed-in resolution and unit + * parameters. */ OpenLayers.Util.getScaleFromResolution = function (resolution, units) { @@ -731,18 +868,33 @@ OpenLayers.Util.getScaleFromResolution = function (resolution, units) { return scale; }; -/** @deprecated Please use directly OpenLayers.Event.stop() passing 'true' as - * the 2nd argument (preventDefault) +/** + * Function: safeStopPropagation + * Deprecated. + * + * This function has been deprecated. Please use directly + * OpenLayers.Event.stop() passing 'true' as the 2nd + * argument (preventDefault) * * Safely stop the propagation of an event *without* preventing * the default browser action from occurring. * - * @param {Event} evt + * Parameter: + * evt - {Event} */ OpenLayers.Util.safeStopPropagation = function(evt) { OpenLayers.Event.stop(evt, true); }; +/** + * Function: pagePositon + * + * Parameters: + * forElement - {DOMElement} + * + * Return:´ + * {Array} two item array, L value then T value. + */ OpenLayers.Util.pagePosition = function(forElement) { var valueT = 0, valueL = 0; @@ -767,7 +919,9 @@ OpenLayers.Util.pagePosition = function(forElement) { }; -/** Test two URLs for equivalence. +/** + * Function: isEquivalentUrl + * Test two URLs for equivalence. * * Setting 'ignoreCase' allows for case-independent comparison. * @@ -779,17 +933,16 @@ OpenLayers.Util.pagePosition = function(forElement) { * - Pathname (for relative <-> absolute comparison) * - Arguments (so they can be out of order) * - * + * Parameters: + * url1 - {String} + * url2 - {String} + * options - {Object} Allows for customization of comparison: + * 'ignoreCase' - Default is True + * 'ignorePort80' - Default is True + * 'ignoreHash' - Default is True * - * @param {String} url1 - * @param {String} url2 - * @param {Object} options allows for customization of comparison: - * 'ignoreCase' - Default is True - * 'ignorePort80' - Default is True - * 'ignoreHash' - Default is True - * - * @returns Whether or not the two URLs are equivalent - * @type Boolean + * Return: + * {Boolean} Whether or not the two URLs are equivalent */ OpenLayers.Util.isEquivalentUrl = function(url1, url2, options) { options = options || new Object(); @@ -851,14 +1004,15 @@ OpenLayers.Util.isEquivalentUrl = function(url1, url2, options) { }; /** - * @private - * - * @param {String} url - * @param {Object} options + * Function: createUrlObject * - * @returns An object with separate url, a, port, host, and args parsed out - * and ready for comparison - * @type Object + * Parameters: + * url - {String} + * options - {Object} + * + * Return: + * {Object} An object with separate url, a, port, host, and args parsed out + * and ready for comparison */ OpenLayers.Util.createUrlObject = function(url, options) { options = options || new Object(); @@ -961,10 +1115,13 @@ OpenLayers.Util.createUrlObject = function(url, options) { }; /** - * @param {String} url + * Function: removeTail * - * @returns The string with all queryString and Hash removed - * @type String + * Parameters: + * url - {String} + * + * Return: + * {String} The string with all queryString and Hash removed */ OpenLayers.Util.removeTail = function(url) { var head = null; @@ -983,8 +1140,11 @@ OpenLayers.Util.removeTail = function(url) { /** - * @returns A string which specifies which is the current - * browser in which we are running. + * Function: getBrowserName + * + * Return: + * {String} A string which specifies which is the current + * browser in which we are running. * * Currently-supported browser detection and codes: * * 'opera' -- Opera @@ -995,8 +1155,6 @@ OpenLayers.Util.removeTail = function(url) { * * If we are unable to property identify the browser, we * return an empty string. - * - * @type String */ OpenLayers.Util.getBrowserName = function() { var browserName = "";