/soc/2012/michael/android: f5645b56981a: Commented buddy classes
Michael Zangl
michael at soc.pidgin.im
Mon Aug 20 10:15:53 EDT 2012
Changeset: f5645b56981a6868c55c784fe0b2a9fa86e655f1
Author: Michael Zangl <michael at soc.pidgin.im>
Date: 2012-08-20 15:17 +0200
Branch: soc.2012.android
URL: http://hg.pidgin.im/soc/2012/michael/android/rev/f5645b56981a
Description:
Commented buddy classes
diffstat:
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java | 98 ++++++++-
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java | 30 +++
2 files changed, 113 insertions(+), 15 deletions(-)
diffs (239 lines):
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
@@ -10,21 +10,55 @@ import im.pidgin.libpurple.icon.PurpleSt
import java.util.LinkedList;
+/**
+ * This is a buddy from the buddy list. Each buddy represents a other account
+ * that our account is connected to and may start an IM conversation with.
+ *
+ * @author michael
+ */
public class PurpleBuddy extends PurpleBlistNode {
+ /**
+ * The listeners that listen to changes of this buddy.
+ */
+ private final LinkedList<PurpleBuddyListener> buddyListeners =
+ new LinkedList<PurpleBuddyListener>();
+ /**
+ * The mutex that synchronizes listeners.
+ */
+ private final Object buddyMutex = new Object();
+
+ /**
+ * Creates a new buddy object.
+ *
+ * @param nativePointer
+ * The native pointer to use
+ * @param manager
+ * The manager
+ */
public PurpleBuddy(long nativePointer, CoreManager manager) {
super(nativePointer, manager);
}
-
- private final LinkedList<PurpleBuddyListener> buddyListeners = new LinkedList<PurpleBuddyListener>();
- private final Object buddyMutex = new Object();
+ /**
+ * Adds a buddy listener.
+ *
+ * @param l
+ * The listener to add.
+ */
public void addBuddyListener(PurpleBuddyListener l) {
synchronized (buddyMutex) {
buddyListeners.add(l);
}
}
+ /**
+ * Removes a buddy listener, if it is in the list of registered buddy
+ * listeners.
+ *
+ * @param l
+ * The buddy listener to remove.
+ */
public void removeBuddyListener(PurpleBuddyListener l) {
synchronized (buddyMutex) {
buddyListeners.remove(l);
@@ -64,7 +98,6 @@ public class PurpleBuddy extends PurpleB
}
}
-
/**
* TODO: Make this more private.
*/
@@ -76,24 +109,46 @@ public class PurpleBuddy extends PurpleB
}
}
+ /**
+ * Returns a buddy's name.
+ *
+ * @return The name.
+ */
public String getName() {
return getName_native();
}
private native String getName_native();
+ /**
+ * Gets the alias for this buddy.
+ *
+ * @return Returns the alias of a buddy. TODO: This method returns the alias
+ * previously set with setAlias. TODO: Provide a getDisplayName()
+ */
public String getAlias() {
return getAlias_native();
}
private native String getAlias_native();
+ /**
+ * Sets a local alias for the buddy.
+ *
+ * @param alias
+ * The local alias, or TODO: null to delete the alias.
+ */
public void setAlias(String alias) {
setAlias_native(alias);
}
private native void setAlias_native(String alias);
-
+
+ /**
+ * Gets the alias the server suggests for this buddy.
+ *
+ * @return The server alias.
+ */
public String getServerAlias() {
return getServerAlias_native();
}
@@ -102,7 +157,7 @@ public class PurpleBuddy extends PurpleB
/**
* Gets the name that should be used to display this buddy.
- *
+ *
* @return The display name, which is the first of alias, parent.alias,
* server_alias, name that is not null.
*/
@@ -112,6 +167,11 @@ public class PurpleBuddy extends PurpleB
private native String getDisplayName_native();
+ /**
+ * Gets the account for the buddy.
+ *
+ * @return The account this buddy is on.
+ */
public PurpleAccount getAccount() {
return getManager().getAccountList().getPeer(getAccount_native());
}
@@ -120,7 +180,7 @@ public class PurpleBuddy extends PurpleB
/**
* Checks if the buddy is online
- *
+ *
* @return true if the account of the buddy is online and the buddy has an
* online presence.
*/
@@ -130,22 +190,29 @@ public class PurpleBuddy extends PurpleB
private native boolean isOnline_native();
+ /**
+ * Gets the contact for this buddy.
+ *
+ * @return A contact object this account is on.
+ */
public PurpleContact getContact() {
PurpleBlistManager blist = getManager().getBlist();
- PurpleBlistNode contact = blist.getPeer(getContact_native());
- if (contact instanceof PurpleContact) {
- return (PurpleContact) contact;
- } else {
- return null;
- }
+ PurpleContact contact = blist.getContactPeer(getContact_native());
+ return contact;
}
private native long getContact_native();
-
+
+ /**
+ * Starts a new conversation with this buddy.
+ *
+ * @return A {@link PurpleConversation} you can register to and send
+ * messages with.
+ */
public PurpleConversation newConversation() {
return getManager().getConversationManager().newConversation(this);
}
-
+
@Override
public PurpleStoredImage getSuggestedIcon() {
PurpleStoredImage customIcon = getCustomIcon();
@@ -157,6 +224,7 @@ public class PurpleBuddy extends PurpleB
/**
* Gets the icon for this buddy that is given by the protocol.
+ *
* @return the icon.
*/
public PurpleStoredImage getIcon() {
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
@@ -1,11 +1,41 @@
package im.pidgin.libpurple.buddy;
+/**
+ * This is a listener interface for classes that want to listen to buddy
+ * changes.
+ *
+ * @author michael
+ */
public interface PurpleBuddyListener {
+ /**
+ * Gets called when the idle status of the buddy changed.
+ *
+ * @param purpleBuddy
+ * The buddy that changed.
+ */
void buddyIdleChanged(PurpleBuddy purpleBuddy);
+ /**
+ * Gets called when the buddy icon was changed.
+ *
+ * @param purpleBuddy
+ * The buddy that changed.
+ */
void buddyIconChanged(PurpleBuddy purpleBuddy);
+ /**
+ * Gets called when the status of the buddy changed.
+ *
+ * @param purpleBuddy
+ * The buddy that changed.
+ */
void buddyStatusChanged(PurpleBuddy purpleBuddy);
+ /**
+ * Gets called when the buddy signed on or off.
+ *
+ * @param purpleBuddy
+ * The buddy that changed.
+ */
void buddySignedOnOff(PurpleBuddy purpleBuddy);
}
More information about the Commits
mailing list