# MessageList
[中文文档](./usage.md)

MessageList is a message list in chatting interface, use to display all kinds of messages, and it can be fully customize.
If you don't define your style, MessageList will use default style.

## Install

We have support several ways to add dependency. You can choose one of them.

- Gradle:
```groovy
compile 'cn.jiguang.imui:messagelist:0.2.0'
```

-  Maven：
```groovy
<dependency>
  <groupId>cn.jiguang.imui</groupId>
  <artifactId>messagelist</artifactId>
  <version>0.2.0</version>
  <type>pom</type>
</dependency>
```

- JitPack
```groovy
// Add in project's build.gradle
allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

// Add in module's build.gradle
dependencies {
    compile 'com.github.jpush:imui:0.2.0'
}
```

## Usage
To use MessageList only need three simple steps, or you can check out our [sample project](./../../sample) to
try it yourself.

### 1. Add MessageList in your xml layout：
```xml
<cn.jiguang.imui.messages.MessageList
    android:id="@+id/msg_list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:avatarHeight="50dp"
    app:avatarWidth="50dp"
    app:bubbleMaxWidth="0.70"
    app:dateTextSize="14sp"
    app:receiveBubblePaddingLeft="20dp"
    app:receiveBubblePaddingRight="10dp"
    app:receiveTextColor="#ffffff"
    app:receiveTextSize="18sp"
    app:sendBubblePaddingLeft="10dp"
    app:sendBubblePaddingRight="20dp"
    app:sendTextColor="#7587A8"
    app:sendTextSize="18sp" />
```
We have define many kinds of attributes, to support user to adjust their layout, you can see
[attrs.xml](./../src/main/res/values/attrs.xml) in detail, and we support totally customize style either, please look down.

### 2. Construct adapter
Adapter's constructor has three parameters. The first one is `sender id`, the id of sender, the second one is `HoldersConfig object`,
you can use this object to [construct your custom ViewHolder and layout](./customLayoutEn.md), the third one is implement of `ImageLoader`,
use to display user's avatar, if this value is null, will not display avatar.([Click here to know more about ImageLoader](./imageLoadEn.md))

```java
MsgListAdapter adapter = new MsgListAdapter<MyMessage>("0", holdersConfig, imageLoader);
messageList.setAdapter(adapter);
```

### 3. Construct model
To be add messages, you need to implement IMessage, IUser interface into your existing model and override it's methods:

```java
public class MyMessage implements IMessage {

    private long id;
    private String text;
    private String timeString;
    private MessageType type;
    private IUser user;
    private String contentFile;
    private long duration;

    public MyMessage(String text, MessageType type) {
        this.text = text;
        this.type = type;
        this.id = UUID.randomUUID().getLeastSignificantBits();
    }

    @Override
    public String getMsgId() {
        return String.valueOf(id);
    }

    @Override
    public IUser getFromUser() {
        if (user == null) {
            return new DefaultUser("0", "user1", null);
        }
        return user;
    }

    public void setUserInfo(IUser user) {
        this.user = user;
    }

    public void setMediaFilePath(String path) {
        this.contentFile = path;
    }

    public void setDuration(long duration) {
        this.duration = duration;
    }

    @Override
    public long getDuration() {
        return duration;
    }

    public void setTimeString(String timeString) {
        this.timeString = timeString;
    }

    @Override
    public String getTimeString() {
        return timeString;
    }

    @Override
    public MessageType getType() {
        return type;
    }

    @Override
    public String getText() {
        return text;
    }

    @Override
    public String getMediaFilePath() {
        return contentFile;
    }
}
```
MessageType above is an enum class in IMessage class, you need implement IUser interface, too:

```java
public class DefaultUser implements IUser {

    private String id;
    private String displayName;
    private String avatar;

    public DefaultUser(String id, String displayName, String avatar) {
        this.id = id;
        this.displayName = displayName;
        this.avatar = avatar;
    }

    @Override
    public String getId() {
        return id;
    }

    @Override
    public String getDisplayName() {
        return displayName;
    }

    @Override
    public String getAvatarFilePath() {
        return avatar;
    }
}
```
That's all! Now you can use your own message model to fill into adapter without type converting of any kind!

## Data management

### Add new messages
To add new message in message list is pretty easy, we support two ways to add new messages:

- Add new message in the bottom of message list： `addToStart(IMESSAGE message, boolean scroll)`

```java
// add a new message in the bottom of message list, the second parameter implys whether to scroll to bottom.
adapter.addToStart(message, true);
```

- Add messages in the top of message list（Usually use this method to load last page of history messages）: `addToEnd(List<IMessage> messages)`

```java
// Add messages to the top of message list, messages should be orderd by date.
adapter.addToEnd(messages);
```

- Scroll to load history messages
After adding this listener: `OnLoadMoreListener`，when scroll to top will fire `onLoadMore` event，for example：
```java
mAdapter.setOnLoadMoreListener(new MsgListAdapter.OnLoadMoreListener() {
    @Override
    public void onLoadMore(int page, int totalCount) {
        if (totalCount < mData.size()) {
             new Handler().postDelayed(new Runnable() {
                 @Override
                 public void run() {
                     mAdapter.addToEnd(mData);
                 }
             }, 1000);
        }
    }
});
```

### Delete message
Here are methods to delete message：

- *adapter.deleteById(String id)*: according message id to delete
- *adapter.deleteByIds(String[] ids)*: according message ids' array to delete
- *adapter.delete(IMessage message)*: according message object to delete
- *adapter.delete(List<IMessage> messages)*: according message objects' list to delete
- *adapter.clear()*: delete all messages

### Update message
If message updated, you can invoke these methods to notify adapter to update message:

- *adapter.update(IMessage message)*: message to be updated
- *adapter.update(String oldId, IMessage newMessage)*


## Event handling
- `OnMsgClickListener` fires when click message.
```java
mAdapter.setOnMsgClickListener(new MsgListAdapter.OnMsgClickListener<MyMessage>() {
    @Override
    public void onMessageClick(MyMessage message) {
        // do something
    }
});
```

- `OnAvatarClickListener` fires when click avatar.
```java
mAdapter.setOnAvatarClickListener(new MsgListAdapter.OnAvatarClickListener<MyMessage>() {
    @Override
    public void onAvatarClick(MyMessage message) {
        DefaultUser userInfo = (DefaultUser) message.getUserInfo();
        // Do something
    }
});
```

- `OnMsgLongClickListener` fires when long click message.
```java
mAdapter.setMsgLongClickListener(new MsgListAdapter.OnMsgLongClickListener<MyMessage>() {
    @Override
    public void onMessageLongClick(MyMessage message) {
        // do something
    }
});
```

- ‘OnMsgResendListener’ fires when click resend button.
```java
mAdapter.setMsgResendListener(new MsgListAdapter.OnMsgResendListener<MyMessage>() {
    @Override
    public void onMessageResend(MyMessage message) {
       // resend message here
    }
 });
```