Merge branch 'master' into igxDragDrop-directive

Author: mpavlinov

projects/igniteui-angular/src/lib/drop-down/drop-down.component.ts

@@ -63,53 +63,99 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
 
     /**
      * Emitted when item selection is changing, before the selection completes
+     *
+     * ```html
+     * <igx-drop-down (onSelection)='handleSelection()'></igx-drop-down>
+     * ```
      */
     @Output()
     public onSelection = new EventEmitter<ISelectionEventArgs>();
 
     /**
      * Emitted before the dropdown is opened
+     *
+     * ```html
+     * <igx-drop-down (onOpening)='handleOpening()'></igx-drop-down>
+     * ```
      */
     @Output()
     public onOpening = new EventEmitter();
 
     /**
      * Emitted after the dropdown is opened
+     *
+     * ```html
+     * <igx-drop-down (onOpened)='handleOpened()'></igx-drop-down>
+     * ```
      */
     @Output()
     public onOpened = new EventEmitter();
 
     /**
      * Emitted before the dropdown is closed
+     *
+     * ```html
+     * <igx-drop-down (onClosing)='handleClosing()'></igx-drop-down>
+     * ```
      */
     @Output()
     public onClosing = new EventEmitter();
 
     /**
      * Emitted after the dropdown is closed
+     *
+     * ```html
+     * <igx-drop-down (onClosed)='handleClosed()'></igx-drop-down>
+     * ```
      */
     @Output()
     public onClosed = new EventEmitter();
 
     /**
-     * Gets/sets the width of the drop down
+     *  Gets the width of the drop down
+     *
+     * ```typescript
+     * // get
+     * let myDropDownCurrentWidth = this.dropdown.width;
+     * ```
      */
     @Input()
     get width() {
         return this._width;
     }
+    /**
+     * Sets the width of the drop down
+     *
+     * ```html
+     * <!--set-->
+     * <igx-drop-down [width]='160px'></igx-drop-down>
+     * ```
+     */
     set width(value) {
         this._width = value;
         this.toggleDirective.element.style.width = value;
     }
 
     /**
-     * Gets/sets the height of the drop down
+     * Gets the height of the drop down
+     *
+     * ```typescript
+     * // get
+     * let myDropDownCurrentHeight = this.dropdown.height;
+     * ```
      */
     @Input()
     get height() {
         return this._height;
     }
+    /**
+     * Sets the height of the drop down
+     *
+     * ```html
+     * <!--set-->
+     * <igx-drop-down [height]='400px'></igx-drop-down>
+     * ```
+     */
     set height(value) {
         this._height = value;
         this.toggleDirective.element.style.height = value;
@@ -118,31 +164,62 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
     /**
      * Gets/sets whether items will be able to take focus. If set to true, default value,
      * user will be able to use keyboard navigation.
+     *
+     * ```typescript
+     * // get
+     * let dropDownAllowsItemFocus = this.dropdown.allowItemsFocus;
+     * ```
+     *
+     * ```html
+     * <!--set-->
+     * <igx-drop-down [allowItemsFocus]='true'></igx-drop-down>
+     * ```
      */
     @Input()
     public allowItemsFocus = true;
 
     /**
-     * Gets/sets the drop down's id
+     * Gets the drop down's id
+     *
+     * ```typescript
+     * // get
+     * let myDropDownCurrentId = this.dropdown.id;
+     * ```
      */
     @Input()
     get id(): string {
         return this._id;
     }
+    /**
+     * Sets the drop down's id
+     *
+     * ```html
+     * <!--set-->
+     * <igx-drop-down [id]='newDropDownId'></igx-drop-down>
+     * ```
+     */
     set id(value: string) {
         this._id = value;
         this.toggleDirective.id = value;
     }
 
     /**
      * Gets if the dropdown is collapsed
+     *
+     * ```typescript
+     * let isCollapsed = this.dropdown.collapsed;
+     * ```
      */
     public get collapsed(): boolean {
         return this.toggleDirective.collapsed;
     }
 
     /**
      * Get currently selected item
+     *
+     * ```typescript
+     * let currentItem = this.dropdown.selectedItem;
+     * ```
      */
     public get selectedItem(): IgxDropDownItemComponent {
         const selection = this.selectionAPI.get_selection(this.id);
@@ -151,6 +228,10 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
 
     /**
      * Get all non-header items
+     *
+     * ```typescript
+     * let myDropDownItems = this.dropdown.items;
+     * ```
      */
     public get items(): IgxDropDownItemComponent[] {
         const items: IgxDropDownItemComponent[] = [];
@@ -167,6 +248,10 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
 
     /**
      * Get all header items
+     *
+     * ```typescript
+     * let myDropDownHeaderItems = this.dropdown.headers;
+     * ```
      */
     public get headers(): IgxDropDownItemComponent[] {
         const headers: IgxDropDownItemComponent[] = [];
@@ -183,6 +268,10 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
 
     /**
      * Get dropdown html element
+     *
+     * ```typescript
+     * let myDropDownElement = this.dropdown.element;
+     * ```
      */
     public get element() {
         return this.elementRef.nativeElement;
@@ -212,20 +301,32 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
 
     /**
      * Opens the dropdown
+     *
+     * ```typescript
+     * this.dropdown.open();
+     * ```
      */
     open() {
         this.toggleDirective.open(true);
     }
 
     /**
      * Closes the dropdown
+     *
+     * ```typescript
+     * this.dropdown.close();
+     * ```
      */
     close() {
         this.toggleDirective.close(true);
     }
 
     /**
      * Toggles the dropdown
+     *
+     * ```typescript
+     * this.dropdown.toggle();
+     * ```
      */
     toggle() {
         if (this.toggleDirective.collapsed) {
@@ -235,6 +336,9 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         }
     }
 
+    /**
+     * @hidden
+     */
     focusFirst() {
         if (this._focusedItem) {
             const focusedItemIndex = - 1;
@@ -245,6 +349,9 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         }
     }
 
+    /**
+     * @hidden
+     */
     focusLast() {
         if (this._focusedItem) {
             const focusedItemIndex = (this.items.length);
@@ -255,6 +362,9 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         }
     }
 
+    /**
+     * @hidden
+     */
     focusNext() {
         let focusedItemIndex = -1;
         if (this._focusedItem) {
@@ -266,6 +376,9 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         }
     }
 
+    /**
+     * @hidden
+     */
     focusPrev() {
         if (this._focusedItem) {
             const focusedItemIndex = this._focusedItem.index;
@@ -276,17 +389,27 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         }
     }
 
+    /**
+     * @hidden
+     */
     ngOnInit() {
         this.toggleDirective.id = this.id;
     }
 
+
+    /**
+     * @hidden
+     */
     onToggleOpening() {
         this.toggleDirective.collapsed = false;
         this.cdr.detectChanges();
         this.scrollToItem(this.selectedItem);
         this.onOpening.emit();
     }
 
+    /**
+     * @hidden
+     */
     onToggleOpened() {
         this._initiallySelectedItem = this.selectedItem;
         this._focusedItem = this.selectedItem;
@@ -301,10 +424,16 @@ export class IgxDropDownComponent implements IToggleView, OnInit {
         this.onOpened.emit();
     }
 
+    /**
+     * @hidden
+     */
     onToggleClosing() {
         this.onClosing.emit();
     }
 
+    /**
+     * @hidden
+     */
     onToggleClosed() {
         if (this._focusedItem) {
             this._focusedItem.isFocused = false;