azone / ratreeview Goto Github PK

#RATreeView (iOS 5.0+) ##Purpose RATreeView is a class designed to support implementation of the Tree View on IOS. It works as a wrapper for the UITableView, defining its own delegate and data source methods for easier managment for tree data structures.

##ARC Compatibility RATreeView is implemented using ARC.

##Installation To use RATreeView in your app, just drag RATreeView class files into your project and add Quartz framework to your project (Quartz is required since version 0.1.0). You can also setup RATreeView in your project using Pods (' pod "RATreeView" ' in your Podfile).

Nextly, just import RATreeView.h header file and use it!

##Introduction As RATreeView is a wrapper for UITableView, most of delegate and data dource methods are just equivalents of specific methods from UITableView delegate and data source protocols. They are changed in the way they provide easier managment for the tree structures. There are also some new methods in protocols to provide support for expanding and collapsing rows of the tree view. It should work on IOS 5.0+.

##RATreeNodeInfo Almost every methods of the RATreeViewDelegate's and RATreeViewDataSource's protocol have the argument of the class RATreeNodeInfo. RATreeNodeInfo is logically connected with item. The purpose of this parameter is to support programmer with as much information as possible.

To make this possible RATreeNodeinfo has the following properties:

@property (nonatomic, getter = isExpanded, readonly) BOOL expanded;

Returns YES if the item's row is expanded.

@property (nonatomic, readonly) NSInteger treeDepthLevel;

Returns level of the item in the tree. The value for to root item children is 0.

@property (strong, nonatomic, readonly) RATreeNode *parent;

Returns object's parent.

@property (strong, nonatomic, readonly) NSArray *children;

Returns object's children.

@property (strong, nonatomic, readonly) id item; 

Returns the item associated with an object.

##RATreeView RATreeView has almost all properties which can be found in UITableView or UIScrollView. #####It also implemements some new properties: @property (nonatomic) RATreeViewRowAnimation rowsExpandingAnimation; Animation used for rows expanding. The default is RATreeViewRowAnimationTop.

 @property (nonatomic) RATreeViewRowAnimation rowsCollapsingAnimation;

Animation used for rows collapsing. The default is RATreeViewRowAnimationBottom.

#####New (comparing to UITableView) methods of the RATreeView: -(void)expandRowForItem:(id)item withRowAnimation:(RATreeViewRowAnimation)rowAnimation;

Expands row which is associated with given item. Item's row must be visible - his parent must be expanded. For no visible items that method do nothing.

 -(void)expandRowForItem:(id)item;

Expands row which is associated with given item. Item's row must be visible - his parent must be expanded. For no visible items that method do nothing. Uses animation type specified in rowsExpandingAnimation property.

 - (void)collapseRowForItem:(id)item withRowAnimation:(RATreeViewAnimation)rowAnimation;

Collapses row which is associated with given item. All children of the specified item will be collapsed.

 - (void)collapseRowForItem:(id)item;

Collapses row which is associated with given item. All children of the specified item will be collapsed. Uses animation type specified in ** rowsCollapsingAnimation property.

 - (void)reloadRows

Reload all rows of the RATreeView without collapsing expanded ones.

##RATreeView Data Source #####RATreeViewDataSource contains following required methods:

(NSInteger)treeView:(RATreeView*)treeView numberOfChildrenOfItem:(id)item;

This method should return the number of the child items encompassed by a given item. If item is nil, this method should return the number of children for the top-level item.

(UITableViewCell *)treeView:(RATreeView *)treeView cellForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo

This method ask the data source for a cell to insert for a particular item.

(id)treeView:(RATreeView *)treeView child:(NSInteger)index ofItem:(id)item;

This returns the child item at the specified index of a given item. If item is nil, returns the appropriate child item of the root object.

#####RATreeViewDataSource contains following optional methods:

- (void)treeView:(RATreeView *)treeView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method ask the data source to commit the insertion or deletion of a specified row.

- (BOOL)treeView:(RATreeView *)treeView canEditRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method ask the data source to verify that the given row is editable. If not implemented all rows are assumed to be editable.

##RATreeView Delegate All methods of RATreeViewDelegate are optional. RATreeViewDelegate contains almost all methods which all available in UITableViewDelegate. For easier managment of the tree view names and arguments of this methods are slightly changed.

For example:

- (CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath;                                    // UITableViewDelegate
- (void)tableView:(UITableView *)tableView willBeginEditingRowAtIndexPath:(NSIndexPath *)indexPath;								        // UITableViewDelegate

is changed to:

 - (CGFloat)treeView:(RATreeView *)treeView heightForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;               // RATreeViewDelegate
 - (void)treeView:(RATreeView *)treeView willBeginEditingRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;  //RATreeViewDelegate

###RATreeViewDelegate contains following methods: ####Expanding and Collapsing

- (BOOL)treeView:(RATreeView *)treeView shouldExpandRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method ask the delegate whether row for the provided item should be expanded due to the user interaction (selection by the user). Called for collapsed rows with at least one child. By default row would be expanded.

- (void)treeView:(RATreeView *)treeView willExpandRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method informs delegate that specific row will be expanded due to the user interaction (selection by the user).

- (void)treeView:(RATreeView *)treeView didExpandRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo

This method informs delegate that specific row was expanded due to the user interaction (selection by the user).

- (BOOL)treeView:(RATreeView *)treeView shouldCollapaseRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This methods ask the delegate whether row for the provided item should be collapsed due to the user interaction. Called for expanded rows with at least one child. By default row would be collapsed.

- (void)treeView:(RATreeView *)treeView willCollapseRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method informs delegate that specific row will be collapsed due to the user interaction.

- (void)treeView:(RATreeView *)treeView didCollapseRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

This method informs delegate that specific row was collapsed due to the user interaction.

- (BOOL)treeView:(RATreeView *)treeView shouldItemBeExpandedAfterDataReload:(id)item treeDepthLevel:(NSInteger)treeDepthLevel;

This method ask the delegate whether the specific row should be expanded after data reload. It is called for every element after each reload of the data of the RATreeView. In case delegate return YES for the item whoose parent (or parents) aren't expanded, all unexpanded parent will be expanded.

####Configuring Rows for the Table View

 - (CGFloat)treeView:(RATreeView *)treeView heightForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate for the height to use for a row with a specified item.

 - (NSInteger)treeView:(RATreeView *)treeView indentationLevelForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate to return the level od indentation for a row with a specified item.

 - (void)treeView:(RATreeView *)treeView willDisplayCell:(UITableViewCell *)cell forItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells a delegate the tree view is about to draw a cell for a particular item.

####Managing Accessory Views

- (void)treeView:(RATreeView *)treeView accessoryButtonTappedForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the user tapped the accessory (disclosure) view associated with a given item.

####Managing Selections

 - (id)treeView:(RATreeView *)treeView willSelectRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that a specified row is about to be selected. Return item another that one passed as an argument to select another row. The item this method returns must be visible (that means its parent must be expanded).

 - (void)treeView:(RATreeView *)treeView didSelectRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the specified row is now selected.

 - (id)treeView:(RATreeView *)treeView willDeselectRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that a specified row is about to be deselected. Return item another that one passed as an argument to deselect another row. The item this method returns must be visible (that means its parent must be expanded).

- (void)treeView:(RATreeView *)treeView didDeselectRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the specified row in now deselected.

####Editing Tree Rows

 - (void)treeView:(RATreeView *)treeView willBeginEditingRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the tree view is about to go into editing mode.This method is called when the user swipes horizontally accross a row.

 - (void)treeView:(RATreeView *)treeView didEndEditingRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the tree view has left editing mode.

- (UITableViewCellEditingStyle)treeView:(RATreeView *)treeView editingStyleForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate for the editing style of a row associated with a specific item.

- (NSString *)treeView:(RATreeView *)treeView titleForDeleteConfirmationButtonForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Changes the default title of the delete-confirmation button. By default, the delete-confirmation button, which appears on the right side of the cell, has the title of “Delete”.

- (BOOL)treeView:(RATreeView *)treeView shouldIndentWhileEditingRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate whether the background of the specified row shuld be indented while the tree view is in editing mode.

####Tracking the Removal of Views

- (void)treeView:(RATreeView *)treeView didEndDisplayingCell:(RATreeViewCell *)cell forItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the specified cell was removed from the tree view.

####Copying and Pasting Row Content

- (BOOL)treeView:(RATreeView *)treeView shouldShowMenuForRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate if the editing menu should be shown for a certain row.

- (BOOL)treeView:(RATreeView *)treeView canPerformAction:(SEL)action forRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo withSender:(id)sender;

Asks the delegate if the editing menu should omit the Copy and or Paste command for a given row.

- (void)treeView:(RATreeView *)treeView performAction:(SEL)action forRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo withSender:(id)sender;

Tells the delegate to perform a copy or paste operation on the content of a given row.

####Managing Tree View Highlighting

- (BOOL)treeView:(RATreeView *)treeView shouldHighlightRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Asks the delegate if the specified row should be highlighted;

- (BOOL)treeView:(RATreeView *)treeView didHighlightRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the specified row was highlighted.

- (BOOL)treeView:(RATreeView *)treeView didUnhighlightRowForItem:(id)item treeNodeInfo:(RATreeNodeInfo *)treeNodeInfo;

Tells the delegate that the highlight was removed from the row associated with a specified item.

##Types For the better encapsulation RATreeView declares some own enums which are equivalents for the enums declared for UITableView and UITableViewCell. These enums are used as properties types and in RATreeView's method calls.

Equivalent for the UITableViewStyle:

typedef enum {
  RATreeViewStylePlain = 0,
  RATreeViewStyleGrouped
} RATreeViewStyle;

Equivalent for the UITableViewCellSeparatorStyle:

typedef enum RATreeViewCellSeparatorStyle {
  RATreeViewCellSeparatorStyleNone = 0,
  RATreeViewCellSeparatorStyleSingleLine,
  RATreeViewCellSeparatorStyleSingleLineEtched
} RATreeViewCellSeparatorStyle;

Equivalent for the UITableViewScrollPosition:

typedef enum RATreeViewScrollPosition {
  RATreeViewScrollPositionNone = 0,
  RATreeViewScrollPositionTop,
  RATreeViewScrollPositionMiddle,
  RATreeViewScrollPositionBottom
} RATreeViewScrollPosition;

Equivalent for the UITableViewRowAnimation:

typedef enum RATreeViewRowAnimation {
  RATreeViewRowAnimationNone = 0,
  RATreeViewRowAnimationRight,
  RATreeViewRowAnimationLeft,
  RATreeViewRowAnimationTop,
  RATreeViewRowAnimationBottom,
  RATreeViewRowAnimationMiddle,
  RATreeViewRowAnimationAutomatic
} RATreeViewRowAnimation;