{"id":13604851,"url":"https://github.com/yarolegovich/DiscreteScrollView","last_synced_at":"2025-04-12T02:32:04.853Z","repository":{"id":39617591,"uuid":"83851056","full_name":"yarolegovich/DiscreteScrollView","owner":"yarolegovich","description":"A scrollable list of items that centers the current element and provides easy-to-use APIs for cool item animations.","archived":false,"fork":false,"pushed_at":"2024-08-19T09:48:41.000Z","size":33353,"stargazers_count":5777,"open_issues_count":44,"forks_count":777,"subscribers_count":95,"default_branch":"master","last_synced_at":"2024-10-29T14:56:22.850Z","etag":null,"topics":["android","android-development","android-library","android-ui","carousel","discrete-scroll","item-picker","layoutmanager","page-transformations","recyclerview","recyclerviewpager","swipe","view","viewpager"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yarolegovich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-03T23:38:54.000Z","updated_at":"2024-10-28T19:22:49.000Z","dependencies_parsed_at":"2022-09-10T20:01:29.044Z","dependency_job_id":null,"html_url":"https://github.com/yarolegovich/DiscreteScrollView","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FDiscreteScrollView","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FDiscreteScrollView/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FDiscreteScrollView/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarolegovich%2FDiscreteScrollView/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yarolegovich","download_url":"https://codeload.github.com/yarolegovich/DiscreteScrollView/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223489678,"owners_count":17153801,"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":["android","android-development","android-library","android-ui","carousel","discrete-scroll","item-picker","layoutmanager","page-transformations","recyclerview","recyclerviewpager","swipe","view","viewpager"],"created_at":"2024-08-01T19:00:51.949Z","updated_at":"2024-11-07T09:31:07.246Z","avatar_url":"https://github.com/yarolegovich.png","language":"Java","readme":"# DiscreteScrollView\n\nThe library is a RecyclerView-based implementation of a scrollable list, where current item is centered and can be changed using swipes.\nIt is similar to a ViewPager, but you can quickly and painlessly create layout, where views adjacent to the currently selected view are partially or fully visible on the screen. \n\n![GifSampleShop](https://github.com/yarolegovich/DiscreteScrollView/blob/master/images/cards_shop.gif)\n\n## Gradle \nAdd this into your dependencies block.\n```\ncompile 'com.yarolegovich:discrete-scrollview:1.5.1'\n```\n\n## Reporting an issue\n\nIf you are going to report an issue, I will greatly appreciate you including some code which I can run to see the issue. By doing so you maximize the chance that I will fix the problem. \n\nBy the way, before reporting a problem, try replacing DiscreteScrollView with a RecyclerView. If the problem is still present, it's likely somewhere in your code.\n\n## Sample\n\u003ca href=\"https://play.google.com/store/apps/details?id=com.yarolegovich.discretescrollview.sample\"\u003e\u003cimg alt=\"Get it on Google Play\" src=\"https://play.google.com/intl/en_us/badges/images/apps/en-play-badge.png\" width=\"185\" height=\"60\"/\u003e\u003c/a\u003e\u003cbr\u003e\n\nPlease see the [sample app](https://github.com/yarolegovich/DiscreteScrollView/tree/master/sample/src/main/java/com/yarolegovich/discretescrollview/sample) for examples of library usage.\n\n![GifSampleWeather](https://github.com/yarolegovich/DiscreteScrollView/blob/master/images/cards_weather.gif)\n\n## Wiki\n### General\nThe library uses a custom LayoutManager to adjust items' positions on the screen and handle scroll, however it is not exposed to the client \ncode. All public API is accessible through DiscreteScrollView class, which is a simple descendant of RecyclerView.\n\nIf you have ever used RecyclerView - you already know how to use this library. One thing to note - you should NOT set LayoutManager.\n\n#### Usage:\n 1. Add DiscreteScrollView to your layout either using xml or code:\n 2. Create your implementation of RecyclerView.Adapter. Refer to the [sample](https://github.com/yarolegovich/DiscreteScrollView/blob/master/sample/src/main/java/com/yarolegovich/discretescrollview/sample/shop/ShopAdapter.java) for an example, if you don't know how to do it.\n 3. Set the adapter.\n 4. You are done! \n```xml\n\u003ccom.yarolegovich.discretescrollview.DiscreteScrollView\n  android:id=\"@+id/picker\"\n  android:layout_width=\"match_parent\"\n  android:layout_height=\"wrap_content\"\n  app:dsv_orientation=\"horizontal|vertical\" /\u003e  \u003c!-- orientation is optional, default is horizontal --\u003e\n```\n```java\nDiscreteScrollView scrollView = findViewById(R.id.picker);\nscrollView.setAdapter(new YourAdapterImplementation());\n```\n\n### API\n#### General\n```java\nscrollView.setOrientation(DSVOrientation o); //Sets an orientation of the view\nscrollView.setOffscreenItems(count); //Reserve extra space equal to (childSize * count) on each side of the view\nscrollView.setOverScrollEnabled(enabled); //Can also be set using android:overScrollMode xml attribute\n```\n#### Related to the current item:\n```java\nscrollView.getCurrentItem(); //returns adapter position of the currently selected item or -1 if adapter is empty.\nscrollView.scrollToPosition(int position); //position becomes selected\nscrollView.smoothScrollToPosition(int position); //position becomes selected with animated scroll\nscrollView.setItemTransitionTimeMillis(int millis); //determines how much time it takes to change the item on fling, settle or smoothScroll\n```\n#### Transformations\nOne useful feature of ViewPager is page transformations. It allows you, for example, to create carousel effect. DiscreteScrollView also supports \npage transformations.\n```java\nscrollView.setItemTransformer(transformer);\n\npublic interface DiscreteScrollItemTransformer {\n    /**\n     * In this method you apply any transform you can imagine (perfomance is not guaranteed).\n     * @param position is a value inside the interval [-1f..1f]. In idle state:\n     * |view1|  |currentlySelectedView|  |view2|\n     * -view1 and everything to the left is on position -1;\n     * -currentlySelectedView is on position 0;\n     * -view2 and everything to the right is on position 1.\n     */\n    void transformItem(View item, float position); \n}\n```\nIn the above example `view1Position == (currentlySelectedViewPosition - n)` and `view2Position == (currentlySelectedViewPosition + n)`, where `n` defaults to 1 and can be changed using the following API:\n```java\nscrollView.setClampTransformProgressAfter(n);\n```\nBecause scale transformation is the most common, I included a helper class - ScaleTransformer, here is how to use it:\n```java\ncityPicker.setItemTransformer(new ScaleTransformer.Builder()\n  .setMaxScale(1.05f) \n  .setMinScale(0.8f) \n  .setPivotX(Pivot.X.CENTER) // CENTER is a default one\n  .setPivotY(Pivot.Y.BOTTOM) // CENTER is a default one\n  .build());\n```\nYou may see how it works on GIFs.\n\n#### Slide through multiple items\n\nTo allow slide through multiple items call:\n```java\nscrollView.setSlideOnFling(true);\n```\nThe default threshold is set to 2100. Lower the threshold, more fluid the animation. You can adjust the threshold by calling:\n```java\nscrollView.setSlideOnFlingThreshold(value);\n```\n\n#### Infinite scroll\nInfinite scroll is implemented on the adapter level:\n```java\nInfiniteScrollAdapter wrapper = InfiniteScrollAdapter.wrap(yourAdapter);\nscrollView.setAdapter(wrapper);\n```\nAn instance of `InfiniteScrollAdapter` has the following useful methods:\n```java\nint getRealItemCount();\n\nint getRealCurrentPosition();\n\nint getRealPosition(int position);\n\n/*\n * You will probably want this method in the following use case:\n * int targetAdapterPosition = wrapper.getClosestPosition(targetPosition);\n * scrollView.smoothScrollTo(targetAdapterPosition);\n * To scroll the data set for the least required amount to reach targetPosition.\n */\nint getClosestPosition(int position); \n```\nCurrently `InfiniteScrollAdapter` handles data set changes inefficiently, so your contributions are welcome. \n#### Disabling scroll\nIt's possible to forbid user scroll in any or specific direction using:\n```java\nscrollView.setScrollConfig(config);\n```\nWhere `config` is an instance of `DSVScrollConfig` enum. The default value enables scroll in any direction.\n#### Callbacks\n* Scroll state changes:\n```java\nscrollView.addScrollStateChangeListener(listener);\nscrollView.removeScrollStateChangeListener(listener);\n\npublic interface ScrollStateChangeListener\u003cT extends ViewHolder\u003e {\n\n  void onScrollStart(T currentItemHolder, int adapterPosition); //called when scroll is started, including programatically initiated scroll\n  \n  void onScrollEnd(T currentItemHolder, int adapterPosition); //called when scroll ends\n  /**\n   * Called when scroll is in progress. \n   * @param scrollPosition is a value inside the interval [-1f..1f], it corresponds to the position of currentlySelectedView.\n   * In idle state:\n   * |view1|  |currentlySelectedView|  |view2|\n   * -view1 is on position -1;\n   * -currentlySelectedView is on position 0;\n   * -view2 is on position 1.\n   * @param currentIndex - index of current view\n   * @param newIndex - index of a view which is becoming the new current\n   * @param currentHolder - ViewHolder of a current view\n   * @param newCurrent - ViewHolder of a view which is becoming the new current\n   */\n  void onScroll(float scrollPosition, int currentIndex, int newIndex, @Nullable T currentHolder, @Nullable T newCurrentHolder); \n}\n```\n* Scroll:\n```java\nscrollView.addScrollListener(listener);\nscrollView.removeScrollListener(listener);\n\npublic interface ScrollListener\u003cT extends ViewHolder\u003e {\n  //The same as ScrollStateChangeListener, but for the cases when you are interested only in onScroll()\n  void onScroll(float scrollPosition, int currentIndex, int newIndex, @Nullable T currentHolder, @Nullable T newCurrentHolder);\n}\n```\n* Current selection changes:\n```java\nscrollView.addOnItemChangedListener(listener);\nscrollView.removeOnItemChangedListener(listener);\n\npublic interface OnItemChangedListener\u003cT extends ViewHolder\u003e {\n  /**\n   * Called when new item is selected. It is similar to the onScrollEnd of ScrollStateChangeListener, except that it is \n   * also called when currently selected item appears on the screen for the first time.\n   * viewHolder will be null, if data set becomes empty \n   */\n  void onCurrentItemChanged(@Nullable T viewHolder, int adapterPosition); \n}\n```\n\n## Special thanks\nThanks to [Tayisiya Yurkiv](https://www.behance.net/yurkivt) for sample app design and beautiful GIFs.\n\n## License\n```\nCopyright 2017 Yaroslav Shevchuk\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":["RecyclerView","Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarolegovich%2FDiscreteScrollView","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyarolegovich%2FDiscreteScrollView","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarolegovich%2FDiscreteScrollView/lists"}