{"id":13396113,"url":"https://github.com/emilsjolander/StickyListHeaders","last_synced_at":"2025-03-13T22:31:44.014Z","repository":{"id":2695423,"uuid":"3688678","full_name":"emilsjolander/StickyListHeaders","owner":"emilsjolander","description":"An android library for section headers that stick to the top","archived":false,"fork":false,"pushed_at":"2021-05-21T09:48:05.000Z","size":3866,"stargazers_count":5509,"open_issues_count":161,"forks_count":1516,"subscribers_count":301,"default_branch":"master","last_synced_at":"2024-10-29T14:57:26.356Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emilsjolander.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-03-11T18:29:18.000Z","updated_at":"2024-10-28T06:06:00.000Z","dependencies_parsed_at":"2022-09-16T11:32:15.652Z","dependency_job_id":null,"html_url":"https://github.com/emilsjolander/StickyListHeaders","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilsjolander%2FStickyListHeaders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilsjolander%2FStickyListHeaders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilsjolander%2FStickyListHeaders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilsjolander%2FStickyListHeaders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emilsjolander","download_url":"https://codeload.github.com/emilsjolander/StickyListHeaders/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243179900,"owners_count":20249186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T18:00:40.520Z","updated_at":"2025-03-13T22:31:43.488Z","avatar_url":"https://github.com/emilsjolander.png","language":"Java","funding_links":[],"categories":["Index `(light-weight pages)`","CN","Index","Java","Libs","Uncategorized"],"sub_categories":["[Emil Sjölander](https://github.com/emilsjolander)","\u003cA NAME=\"Widget\"\u003e\u003c/A\u003eWidget","Uncategorized"],"readme":"StickyListHeaders\n=================\nStickyListHeaders is an Android library that makes it easy to integrate section headers in your `ListView`. These section headers stick to the top like in the new People app of Android 4.0 Ice Cream Sandwich. This behavior is also found in lists with sections on iOS devices. This library can also be used without the sticky functionality if you just want section headers.\n\nStickyListHeaders actively supports android versions 2.3 (gingerbread) and above.\nThat said, it works all the way down to 2.1 but is not actively tested or working perfectly.\n\nHere is a short gif showing the functionality you get with this library:\n\n![alt text](https://github.com/emilsjolander/StickyListHeaders/raw/master/demo.gif \"Demo gif\")\n\n\nGoal\n----\nThe goal of this project is to deliver a high performance replacement to `ListView`. You should with minimal effort and time be able to add section headers to a list. This should be done via a simple to use API without any special features. This library will always priorities general use cases over special ones. This means that the library will add very few public methods to the standard `ListView` and will not try to work for every use case. While I will want to support even narrow use cases I will not do so if it compromises the API or any other feature.\n\n\nInstalling\n---------------\n###Maven\nAdd the following maven dependency exchanging `x.x.x` for the latest release.\n```XML\n\u003cdependency\u003e\n    \u003cgroupId\u003ese.emilsjolander\u003c/groupId\u003e\n    \u003cartifactId\u003estickylistheaders\u003c/artifactId\u003e\n    \u003cversion\u003ex.x.x\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n###Gradle\nAdd the following gradle dependency exchanging `x.x.x` for the latest release.\n```groovy\ndependencies {\n    compile 'se.emilsjolander:stickylistheaders:x.x.x'\n}\n```\n\n###Cloning\nFirst of all you will have to clone the library.\n```shell\ngit clone https://github.com/emilsjolander/StickyListHeaders.git\n```\n\nNow that you have the library you will have to import it into Android Studio.\nIn Android Studio navigate the menus like this.\n```\nFile -\u003e Import Project ...\n```\nIn the following dialog navigate to StickyListHeaders which you cloned to your computer in the previous steps and select the `build.gradle`.\n\nGetting Started\n---------------\n###Base usage\n\nOk lets start with your activities or fragments xml file. It might look something like this.\n```xml\n\u003cse.emilsjolander.stickylistheaders.StickyListHeadersListView\n    android:id=\"@+id/list\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\"/\u003e\n```\n\nNow in your activities `onCreate()` or your fragments `onCreateView()` you would want to do something like this\n```java\nStickyListHeadersListView stickyList = (StickyListHeadersListView) findViewById(R.id.list);\nMyAdapter adapter = new MyAdapter(this);\nstickyList.setAdapter(adapter);\n```\n\n`MyAdapter` in the above example would look something like this if your list was a list of countries where each header was for a letter in the alphabet.\n```java\npublic class MyAdapter extends BaseAdapter implements StickyListHeadersAdapter {\n\n    private String[] countries;\n    private LayoutInflater inflater;\n\n    public MyAdapter(Context context) {\n        inflater = LayoutInflater.from(context);\n        countries = context.getResources().getStringArray(R.array.countries);\n    }\n\n    @Override\n    public int getCount() {\n        return countries.length;\n    }\n\n    @Override\n    public Object getItem(int position) {\n        return countries[position];\n    }\n\n    @Override\n    public long getItemId(int position) {\n        return position;\n    }\n\n    @Override \n    public View getView(int position, View convertView, ViewGroup parent) {\n        ViewHolder holder;\n\n        if (convertView == null) {\n            holder = new ViewHolder();\n            convertView = inflater.inflate(R.layout.test_list_item_layout, parent, false);\n            holder.text = (TextView) convertView.findViewById(R.id.text);\n            convertView.setTag(holder);\n        } else {\n            holder = (ViewHolder) convertView.getTag();\n        }\n\n        holder.text.setText(countries[position]);\n\n        return convertView;\n    }\n\n    @Override \n    public View getHeaderView(int position, View convertView, ViewGroup parent) {\n        HeaderViewHolder holder;\n        if (convertView == null) {\n            holder = new HeaderViewHolder();\n            convertView = inflater.inflate(R.layout.header, parent, false);\n            holder.text = (TextView) convertView.findViewById(R.id.text);\n            convertView.setTag(holder);\n        } else {\n            holder = (HeaderViewHolder) convertView.getTag();\n        }\n        //set header text as first char in name\n        String headerText = \"\" + countries[position].subSequence(0, 1).charAt(0);\n        holder.text.setText(headerText);\n        return convertView;\n    }\n\n    @Override\n    public long getHeaderId(int position) {\n        //return the first character of the country as ID because this is what headers are based upon\n        return countries[position].subSequence(0, 1).charAt(0);\n    }\n\n    class HeaderViewHolder {\n        TextView text;\n    }\n\n    class ViewHolder {\n        TextView text;\n    }\n    \n}\n```\n\nThat's it! Look through the API docs below to get know about things to customize and if you have any problems getting started please open an issue as it probably means the getting started guide need some improvement!\n\n###Styling\n\nYou can apply your own theme to `StickyListHeadersListView`s. Say you define a style called `Widget.MyApp.ListView` in values/styles.xml:\n```xml\n\u003cresources\u003e\n    \u003cstyle name=\"Widget.MyApp.ListView\" parent=\"@android:style/Widget.ListView\"\u003e\n        \u003citem name=\"android:paddingLeft\"\u003e@dimen/vertical_padding\u003c/item\u003e\n        \u003citem name=\"android:paddingRight\"\u003e@dimen/vertical_padding\u003c/item\u003e\n    \u003c/style\u003e\n\u003c/resources\u003e\n```\n\nYou can then apply this style to all `StickyListHeadersListView`s by adding something like this to your theme (e.g. values/themes.xml):\n```xml\n\u003cresources\u003e\n    \u003cstyle name=\"Theme.MyApp\" parent=\"android:Theme.NoTitleBar\"\u003e\n        \u003citem name=\"stickyListHeadersListViewStyle\"\u003e@style/Widget.MyApp.ListView\u003c/item\u003e\n    \u003c/style\u003e\n\u003c/resources\u003e\n```\n\n###Expandable support\nNow, you can use `ExpandableStickyListHeadersListView` to expand/collapse subitems.\nxml first\n```xml\n\u003cse.emilsjolander.stickylistheaders.ExpandableStickyListHeadersListView\n    android:id=\"@+id/list\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\"/\u003e\n```\nThen you need to setup your listview on `onCreate()` or `onCreateView()`：\n```java\nExpandableStickyListHeadersListView expandableStickyList = (ExpandableStickyListHeadersListView) findViewById(R.id.list);\nStickyListHeadersAdapter adapter = new MyAdapter(this);\nexpandableStickyList.setAdapter(adapter);\nexpandableStickyList.setOnHeaderClickListener(new StickyListHeadersListView.OnHeaderClickListener() {\n            @Override\n            public void onHeaderClick(StickyListHeadersListView l, View header, int itemPosition, long headerId, boolean currentlySticky) {\n                if(expandableStickyList.isHeaderCollapsed(headerId)){\n                    expandableStickyList.expand(headerId);\n                }else {\n                    expandableStickyList.collapse(headerId);\n                }\n            }\n        });\n```\nAs you see, MyAdapter is just a StickyListHeadersAdapter which is mentioned in the previous section.\nYou needn't do any more extra operations.\n\nThere are three important functions:\n`isHeaderCollapsed(long headerId)`,`expand(long headerId)` and `collapse(long headerId)`.\n\nThe function `isHeaderCollapsed` is used to check whether the subitems belonging to the header have collapsed.\nYou can call `expand` or `collapse` method to hide or show subitems.\nYou can also define a AnimationExecutor which implements `ExpandableStickyListHeadersListView.IAnimationExecutor`,\nand put it into the ExpandableStickyListHeadersListView by `setAnimExecutor` method,if you want more fancy animation when hiding or showing subitems.\n\n\nUpgrading from 1.x versions\n---------------------------\nFirst of all the package name has changed from `com.emilsjolander.components.stickylistheaders` -\u003e `se.emilsjolander.stickylistheaders` so update all your imports and xml files using StickyListHeaders!\n\nIf you are Upgrading from a version prior to 2.x you might run into the following problems.\n1. `StickyListHeadersListView` is no longer a `ListView` subclass. This means that it cannot be passed into a method expecting a ListView. You can retrieve an instance of the `ListView` via `getWrappedList()` but use this with caution as things will probably break if you start setting things directly on that list.\n2. Because `StickyListHeadersListView` is no longer a `ListView` it does not support all the methods. I have implemented delegate methods for all the usual methods and gladly accept pull requests for more.\n\nAPI\n---\n###StickyListHeadersAdapter\n```java\npublic interface StickyListHeadersAdapter extends ListAdapter {\n    View getHeaderView(int position, View convertView, ViewGroup parent);\n    long getHeaderId(int position);\n}\n```\nYour adapter must implement this interface to function with `StickyListHeadersListView`.\n`getHeaderId()` must return a unique integer for every section. A valid implementation for a list with alphabetical sections is the return the char value of the section that `position` is a part of.\n\n`getHeaderView()` works exactly like `getView()` in a regular `ListAdapter`.\n\n\n###StickyListHeadersListView\nHeaders are sticky by default but that can easily be changed with this setter. There is of course also a matching getter for the sticky property.\n```java\npublic void setAreHeadersSticky(boolean areHeadersSticky);\npublic boolean areHeadersSticky();\n```\n\nA `OnHeaderClickListener` is the header version of OnItemClickListener. This is the setter for it and the interface of the listener. The currentlySticky boolean flag indicated if the header that was clicked was sticking to the top at the time it was clicked.\n```java\npublic void setOnHeaderClickListener(OnHeaderClickListener listener);\n\npublic interface OnHeaderClickListener {\n    public void onHeaderClick(StickyListHeadersListView l, View header, int itemPosition, long headerId, boolean currentlySticky);\n}\n```\n\nA `OnStickyHeaderOffsetChangedListener` is a Listener used for listening to when the sticky header slides out of the screen. The offset parameter will slowly grow to be the same size as the headers height. Use the listeners callback to transform the header in any way you see fit, the standard android contacts app dims the text for example.\n```java\npublic void setOnStickyHeaderOffsetChangedListener(OnStickyHeaderOffsetChangedListener listener);\n\npublic interface OnStickyHeaderOffsetChangedListener {\n    public void onStickyHeaderOffsetChanged(StickyListHeadersListView l, View header, int offset);\n}\n```\n\nA `OnStickyHeaderChangedListener` listens for changes to the header.  This enables UI elements elsewhere to react to the current header (e.g. if each header is a date, then the rest of the UI can update when you scroll to a new date).\n```java\npublic void setOnStickyHeaderChangedListener(OnStickyHeaderChangedListener listener);\n\npublic interface OnStickyHeaderChangedListener {\n    void onStickyHeaderChanged(StickyListHeadersListView l, View header, int itemPosition, long headerId);\n}\n```\n\nHere are two methods added to the API for inspecting the children of the underlying `ListView`. I could not override the normal `getChildAt()` and `getChildCount()` methods as that would mess up the underlying measurement system of the `FrameLayout` wrapping the `ListView`.\n```java\npublic View getListChildAt(int index);\npublic int getListChildCount();\n```\n\nThis is a setter and getter for an internal attribute that controls if the list should be drawn under the stuck header. The default value is true. If you do not want to see the list scroll under your header you will want to set this attribute to `false`.\n```java\npublic void setDrawingListUnderStickyHeader(boolean drawingListUnderStickyHeader);\npublic boolean isDrawingListUnderStickyHeader();\n```\n\nIf you are using a transparent action bar the following getter+setter will be very helpful. Use them to set the position of the sticky header from the top of the view.\n```java\npublic void setStickyHeaderTopOffset(int stickyHeaderTopOffset);\npublic int getStickyHeaderTopOffset();\n```\n\nGet the amount of overlap the sticky header has when position in on the top of the list.\n```java\npublic int getHeaderOverlap(int position);\n```\n\nContributing\n------------\nContributions are very welcome. Now that this library has grown in popularity i have a hard time keeping upp with all the issues while tending to a multitude of other projects as well as school. So if you find a bug in the library or want a feature and think you can fix it yourself, fork + pull request and i will greatly appreciate it!\n\nI love getting pull requests for new features as well as bugs. However, when it comes to new features please also explain the use case and way you think the library should include it. If you don't want to start coding a feature without knowing if the feature will have chance of being included, open an issue and we can discuss the feature!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilsjolander%2FStickyListHeaders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femilsjolander%2FStickyListHeaders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilsjolander%2FStickyListHeaders/lists"}