{"action":"created","issue":{"url":"https://api.github.com/repos/atom/atom/issues/5038","labels_url":"https://api.github.com/repos/atom/atom/issues/5038/labels{/name}","comments_url":"https://api.github.com/repos/atom/atom/issues/5038/comments","events_url":"https://api.github.com/repos/atom/atom/issues/5038/events","html_url":"https://github.com/atom/atom/issues/5038","id":54260947,"number":5038,"title":"API for Creating Custom Gutters","user":{"login":"jssln","id":1017111,"avatar_url":"https://avatars.githubusercontent.com/u/1017111?v=3","gravatar_id":"","url":"https://api.github.com/users/jssln","html_url":"https://github.com/jssln","followers_url":"https://api.github.com/users/jssln/followers","following_url":"https://api.github.com/users/jssln/following{/other_user}","gists_url":"https://api.github.com/users/jssln/gists{/gist_id}","starred_url":"https://api.github.com/users/jssln/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jssln/subscriptions","organizations_url":"https://api.github.com/users/jssln/orgs","repos_url":"https://api.github.com/users/jssln/repos","events_url":"https://api.github.com/users/jssln/events{/privacy}","received_events_url":"https://api.github.com/users/jssln/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/atom/atom/labels/enhancement","name":"enhancement","color":"bfd4f2"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":14,"created_at":"2015-01-13T22:58:36Z","updated_at":"2015-02-27T21:59:59Z","closed_at":null,"body":"## Motivation ##\r\nThe Decorations API allows you to attach a class to gutters (and other things) and thus style them. However, we are working on a feature that requires us to be able to add our own HTML elements to the gutter, and would like to propose an API to do that.\r\n\r\n**Feature:**\r\nWe would like to add buttons to the gutter next to lines that contain a test definition. Clicking on the button would run that test. (This is similar to functionality in Xcode.)\r\n\r\n**Why CSS doesn't work:**\r\nAdding CSS only allows us to create “buttons” via :before or :after pseudo-elements. These elements can't respond to events targeted to them; instead, any events they receive will register on the existing “line-number” gutter element. The gutter element already has another action to take in response to a click: it may expand or collapse a section of code. If we tried to add events to the gutter element itself (instead of a new child div), our events would conflict with the existing events from Atom.\r\n\r\n**How the Line Numbers in the Gutter Work, Currently:**\r\nWhen the editor is scrolled, line-number divs that have scrolled offscreen are removed, and new line-number divs for newly onscreen lines are added. The changes are primarily in the GutterComponent class, in “appendOrUpdateVisibleLineNumberNodes” (which calls into “buildLineNumberHTML”) and “removeLineNumberNodes”.\r\n\r\n**Proposed Change:**\r\n1. The most flexibility that an Atom API could offer is the ability to accept a function that will be run on each line-number div after it's added (and before it's removed, for any teardown work). In practice, this could lead to changes that affect things that might be considered “core” to Atom's look. It seems like this opens too much flexibility.\r\n2. A more pared-down API that Atom could offer is the ability to add a column next to the gutter (either on the left side or right side, though it's understandable to limit this to the left side because the right side is occupied by “foldability”). The API for a Gutter object would accept a function that is given the line number, and returns a div for that line number, which would be inserted into the DOM next to the appropriate line number. (It would make sense for this insertion to be done in Atom Core code, because it already manages the positioning of the line numbers and does this via absolute positioning for performance optimisation.) \r\n\r\n\r\n\r\n## Desired Gutter Features ##\r\n**Adding Gutters**\r\n* Create gutter\r\n    * You will most likely create one gutter instance per editor instance.\r\n* API to add a gutter to an editor\r\n    * Indicate whether to position it to the left or right of the line numbers\r\n    * Pass a “z-index” of sorts to indicate how close/far from the edge it should be, similar to the “priority” argument to Atom.Workspace.add---Panel.\r\n\r\n**Removing Gutters**\r\n* Remove from view (toggle)\r\n* Destroy\r\n\r\n**Gutter Properties to Set**\r\n* Set the width (?)\r\n\r\n**Modifying Gutter Contents**\r\n* Insert something inside a div next to each line\r\n    * Initialize the Gutter object with a function that operates on a line number and returns a DOM element. As line-number divs are inserted and removed as the user scrolls, this function is run to determine what to place in the custom gutter next to each line number.\r\n    * API could also allow:\r\n        * Changing this function\r\n        * Clear all the items in the gutter (a convenience)\r\n    * For performance, by default, this function could run just once at initialization on the currently-displayed line numbers, and be run on progressively more line numbers as the user scrolls. The results could be cached.\r\n        * The Gutter API should also expose a method that triggers the function to be run on the currently-displayed line numbers, or on a specific line. This could be useful if you want to update the gutter without the editor being scrolled.\r\n\r\n\r\n\r\n\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/atom/atom/issues/comments/76479963","html_url":"https://github.com/atom/atom/issues/5038#issuecomment-76479963","issue_url":"https://api.github.com/repos/atom/atom/issues/5038","id":76479963,"user":{"login":"kans","id":986627,"avatar_url":"https://avatars.githubusercontent.com/u/986627?v=3","gravatar_id":"","url":"https://api.github.com/users/kans","html_url":"https://github.com/kans","followers_url":"https://api.github.com/users/kans/followers","following_url":"https://api.github.com/users/kans/following{/other_user}","gists_url":"https://api.github.com/users/kans/gists{/gist_id}","starred_url":"https://api.github.com/users/kans/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kans/subscriptions","organizations_url":"https://api.github.com/users/kans/orgs","repos_url":"https://api.github.com/users/kans/repos","events_url":"https://api.github.com/users/kans/events{/privacy}","received_events_url":"https://api.github.com/users/kans/received_events","type":"User","site_admin":false},"created_at":"2015-02-27T21:59:59Z","updated_at":"2015-02-27T21:59:59Z","body":"This would really be a useful addition.  I'd like to drop an img into the gutter which can only be resolved at run time.  The existing solutions are either fragile or extremely heavy handed."}}