Repository: bokeh/bokeh

Issue:
Add ColorBar public JS API definition
Add ColorBar public JS API definition



Discussion:

Resolving patch:
diff --git a/bokeh/models/annotations.py b/bokeh/models/annotations.py
--- a/bokeh/models/annotations.py
+++ b/bokeh/models/annotations.py
@@ -132,23 +132,26 @@ class ColorBar(Annotation):
 
     location = Either(Enum(LegendLocation), Tuple(Float, Float),
         default="top_right", help="""
-    The location where the ColorBar should draw itself. It's either one of
+    The location where the color bar should draw itself. It's either one of
     ``bokeh.core.enums.LegendLocation``'s enumerated values, or a ``(x, y)``
     tuple indicating an absolute location absolute location in screen
     coordinates (pixels from the bottom-left corner).
+
+    .. warning::
+        If the color bar is placed in a side panel, the location will likely
+        have to be set to `(0,0)`.
     """)
 
     orientation = Enum(Orientation, default="vertical", help="""
-    Whether the legend entries should be placed vertically or horizontally
-    when they are layed out.
+    Whether the color bar should be oriented vertically or horizontally.
     """)
 
-    legend_height = Either(Auto, Int(), help="""
-    The height (in pixels) that the rendered legend should occupy.
+    height = Either(Auto, Int(), help="""
+    The height (in pixels) that the color scale should occupy.
     """)
 
-    legend_width = Either(Auto, Int(), help="""
-    The width (in pixels) that the rendered legend should occupy.
+    width = Either(Auto, Int(), help="""
+    The width (in pixels) that the color scale should occupy.
     """)
 
     scale_alpha = Float(1.0, help="""
@@ -168,7 +171,7 @@ class ColorBar(Annotation):
     title_text_font_style = Override(default="italic")
 
     title_standoff = Int(2, help="""
-    The distance (in pixels) to separate the title from the ColorBar.
+    The distance (in pixels) to separate the title from the color bar.
     """)
 
     ticker = Instance(Ticker, default=lambda: BasicTicker(), help="""
@@ -176,8 +179,7 @@ class ColorBar(Annotation):
     """)
 
     formatter = Instance(TickFormatter, default=lambda: BasicTickFormatter(), help="""
-    A TickFormatter to use for formatting the visual appearance
-    of ticks.
+    A TickFormatter to use for formatting the visual appearance of ticks.
     """)
 
     color_mapper = Instance(ColorMapper, help="""
@@ -188,16 +190,12 @@ class ColorBar(Annotation):
         and tick labels won't be rendered.
     """)
 
-    legend_margin = Int(30, help="""
-    Amount of margin around the legend.
+    margin = Int(30, help="""
+    Amount of margin (in pixels) around the outside of the color bar.
     """)
 
-    legend_padding = Int(10, help="""
-    Amount of padding around the contents of the legend.
-    """)
-
-    label_standoff = Int(5, help="""
-    The distance (in pixels) to separate the tick labels from the ColorBar.
+    padding = Int(10, help="""
+    Amount of padding (in pixels) between the color scale and color bar border.
     """)
 
     major_label_props = Include(TextProps, help="""
@@ -210,6 +208,10 @@ class ColorBar(Annotation):
 
     major_label_text_font_size = Override(default={'value': "8pt"})
 
+    label_standoff = Int(5, help="""
+    The distance (in pixels) to separate the tick labels from the color bar.
+    """)
+
     major_tick_props = Include(LineProps, help="""
     The %s of the major ticks.
     """)
@@ -217,12 +219,12 @@ class ColorBar(Annotation):
     major_tick_line_color = Override(default="#ffffff")
 
     major_tick_in = Int(default=5, help="""
-    The distance in pixels that major ticks should extend into the
+    The distance (in pixels) that major ticks should extend into the
     main plot area.
     """)
 
     major_tick_out = Int(default=0, help="""
-    The distance in pixels that major ticks should extend out of the
+    The distance (in pixels) that major ticks should extend out of the
     main plot area.
     """)
 
@@ -233,29 +235,29 @@ class ColorBar(Annotation):
     minor_tick_line_color = Override(default=None)
 
     minor_tick_in = Int(default=0, help="""
-    The distance in pixels that minor ticks should extend into the
+    The distance (in pixels) that minor ticks should extend into the
     main plot area.
     """)
 
     minor_tick_out = Int(default=0, help="""
-    The distance in pixels that major ticks should extend out of the
+    The distance (in pixels) that major ticks should extend out of the
     main plot area.
     """)
 
     bar_props = Include(LineProps, help="""
-    The %s for the colorbar outline.
+    The %s for the color scale bar outline.
     """)
 
     bar_line_color = Override(default=None)
 
     border_props = Include(LineProps, help="""
-    The %s for the colorbar border outline.
+    The %s for the color bar border outline.
     """)
 
     border_line_color = Override(default=None)
 
     background_props = Include(FillProps, help="""
-    The %s for the colorbar background style.
+    The %s for the color bar background style.
     """)
 
     background_fill_color = Override(default="#ffffff")


Test patch:
diff --git a/bokeh/models/tests/test_annotations.py b/bokeh/models/tests/test_annotations.py
--- a/bokeh/models/tests/test_annotations.py
+++ b/bokeh/models/tests/test_annotations.py
@@ -52,16 +52,16 @@ def test_ColorBar():
     assert color_bar.plot is None
     assert color_bar.location == 'top_right'
     assert color_bar.orientation == 'vertical'
-    assert color_bar.legend_height == 'auto'
-    assert color_bar.legend_width == 'auto'
+    assert color_bar.height == 'auto'
+    assert color_bar.width == 'auto'
     assert color_bar.scale_alpha == 1.0
     assert color_bar.title is None
     assert color_bar.title_standoff == 2
     assert isinstance(color_bar.ticker, BasicTicker)
     assert isinstance(color_bar.formatter, BasicTickFormatter)
     assert color_bar.color_mapper is None
-    assert color_bar.legend_margin == 30
-    assert color_bar.legend_padding == 10
+    assert color_bar.margin == 30
+    assert color_bar.padding == 10
     assert color_bar.label_standoff == 5
     assert color_bar.major_tick_in == 5
     assert color_bar.major_tick_out == 0
@@ -80,16 +80,16 @@ def test_ColorBar():
         "visible",
         "location",
         "orientation",
-        "legend_height",
-        "legend_width",
+        "height",
+        "width",
         "scale_alpha",
         "title",
         "title_standoff",
         "ticker",
         "formatter",
         "color_mapper",
-        "legend_margin",
-        "legend_padding",
+        "margin",
+        "padding",
         "label_standoff",
         "major_tick_in",
         "major_tick_out",
diff --git a/bokehjs/test/models/annotations/color_bar.coffee b/bokehjs/test/models/annotations/color_bar.coffee
--- a/bokehjs/test/models/annotations/color_bar.coffee
+++ b/bokehjs/test/models/annotations/color_bar.coffee
@@ -93,10 +93,10 @@ describe "ColorBar module", ->
           beforeEach ->
             @plot.add_layout(@color_bar)
 
-          it "Should use set `legend_width` and `legend_height` if set", ->
+          it "Should use set `width` and `height` if set", ->
             @color_bar.color_mapper = new LinearColorMapper({low: 1, high: 100, palette: Viridis.Viridis3})
-            @color_bar.legend_width = 100
-            @color_bar.legend_height = 200
+            @color_bar.width = 100
+            @color_bar.height = 200
 
             image_dimensions = @color_bar._computed_image_dimensions()
             expect(image_dimensions.width).to.be.equal(100)
@@ -130,14 +130,14 @@ describe "ColorBar module", ->
             document = new Document()
             document.add_root(@plot)
 
-          it "Should return height = plot.height - 2 * legend_padding for any palette in side panel", ->
+          it "Should return height = plot.height - 2 * padding for any palette in side panel", ->
 
             @color_bar.color_mapper = new LinearColorMapper({low: 1, high: 100, palette: Viridis.Viridis3})
             @color_bar.title = "I'm a title"
 
             image_dimensions = @color_bar._computed_image_dimensions()
             expect(image_dimensions.width).to.be.equal(25)
-            # height = 500 (plot.height) - 2 * 10 (color_bar.legend_padding) - 17 (title_height)
+            # height = 500 (plot.height) - 2 * 10 (color_bar.padding) - 17 (title_height)
             expect(image_dimensions.height).to.be.equal(463)
 
         describe "ColorBar.orientation = 'horizontal'", ->
@@ -146,10 +146,10 @@ describe "ColorBar module", ->
             @color_bar.orientation = 'horizontal'
             @plot.add_layout(@color_bar)
 
-          it "Should use set `legend_width` and `legend_height` if set", ->
+          it "Should use set `width` and `height` if set", ->
             @color_bar.color_mapper = new LinearColorMapper({low: 1, high: 100, palette: Viridis.Viridis3})
-            @color_bar.legend_width = 100
-            @color_bar.legend_height = 200
+            @color_bar.width = 100
+            @color_bar.height = 200
 
             image_dimensions = @color_bar._computed_image_dimensions()
             expect(image_dimensions.width).to.be.equal(100)
@@ -173,7 +173,7 @@ describe "ColorBar module", ->
             @color_bar.color_mapper = new LinearColorMapper({low: 1, high: 100, palette: Viridis.Viridis256})
 
             image_dimensions = @color_bar._computed_image_dimensions()
-            # width = 500 (plot.width) * 0.8 - 2 * 10 (color_bar.legend_padding)
+            # width = 500 (plot.width) * 0.8 - 2 * 10 (color_bar.padding)
             expect(image_dimensions.width).to.be.equal(380)
             expect(image_dimensions.height).to.be.equal(25)
 
@@ -185,12 +185,12 @@ describe "ColorBar module", ->
             document = new Document()
             document.add_root(@plot)
 
-          it "Should return width = plot.width - 2 * legend_padding for any palette in side panel", ->
+          it "Should return width = plot.width - 2 * padding for any palette in side panel", ->
             @color_bar.color_mapper = new LinearColorMapper({low: 1, high: 100, palette: Viridis.Viridis10})
             @color_bar.title = "I'm a title"
 
             image_dimensions = @color_bar._computed_image_dimensions()
-            # width = 500 (plot.width) - 2 * 10 (color_bar.legend_padding)
+            # width = 500 (plot.width) - 2 * 10 (color_bar.padding)
             expect(image_dimensions.width).to.be.equal(480)
             expect(image_dimensions.height).to.be.equal(25)
 
@@ -203,7 +203,7 @@ describe "ColorBar module", ->
 
       it "Should correctly tick coords and labels for LinearColorMapper if orientation='vertical'", ->
         @color_bar.color_mapper = new LinearColorMapper({low: 10, high: 20, palette: Viridis.Viridis10})
-        @color_bar.legend_height = 100
+        @color_bar.height = 100
         @color_bar.orientation = 'vertical'
 
         tick_coords = @color_bar._tick_coordinates()
@@ -214,7 +214,7 @@ describe "ColorBar module", ->
 
       it "Should correctly determine tick coords and labels for LinearColorMapperif orientation='horizontal'", ->
         @color_bar.color_mapper = new LinearColorMapper({low: 10, high: 20, palette: Viridis.Viridis10})
-        @color_bar.legend_width = 100
+        @color_bar.width = 100
         @color_bar.orientation = 'horizontal'
 
         tick_coords = @color_bar._tick_coordinates()
@@ -225,7 +225,7 @@ describe "ColorBar module", ->
 
       it "Should correctly determine tick coords and labels for LogColorMapper if orientation='vertical'", ->
         @color_bar.color_mapper = new LogColorMapper({low: 0, high: 1000, palette: Viridis.Viridis10})
-        @color_bar.legend_height = 100
+        @color_bar.height = 100
         @color_bar.orientation = 'vertical'
 
         tick_coords = @color_bar._tick_coordinates()
@@ -236,7 +236,7 @@ describe "ColorBar module", ->
 
       it "Should correctly determine tick coords and labels for LogColorMapper if orientation='vertical'", ->
         @color_bar.color_mapper = new LogColorMapper({low: 0, high: 1000, palette: Viridis.Viridis10})
-        @color_bar.legend_width = 100
+        @color_bar.width = 100
         @color_bar.orientation = 'horizontal'
 
         tick_coords = @color_bar._tick_coordinates()
@@ -287,15 +287,15 @@ describe "ColorBar module", ->
 
     it "ColorBar.View.compute_legend_dimensions method (orientation='vertical')", ->
       # Note: ctx.measureText is stubbed to return {'width': 1, 'ascent': 1} in test/utils
-      @color_bar.legend_height = 100
-      @color_bar.legend_width = 25
+      @color_bar.height = 100
+      @color_bar.width = 25
 
       expect(@color_bar_view.compute_legend_dimensions()).to.be.deep.equal({ height: 120, width: 51 })
 
     it "ColorBar.View.compute_legend_dimensions method (orientation='horizontal')", ->
       @color_bar.orientation = "horizontal"
-      @color_bar.legend_height = 25
-      @color_bar.legend_width = 100
+      @color_bar.height = 25
+      @color_bar.width = 100
 
       expect(@color_bar_view.compute_legend_dimensions()).to.be.deep.equal({ height: 65, width: 120 })
 
diff --git a/tests/integration/annotations/test_color_bar.py b/tests/integration/annotations/test_color_bar.py
--- a/tests/integration/annotations/test_color_bar.py
+++ b/tests/integration/annotations/test_color_bar.py
@@ -17,8 +17,8 @@ def create_vertical_color_bar_with_log_cmap(height='auto', width='auto'):
     color_mapper = LogColorMapper(low=1, high=100000, palette='Viridis256')
     color_bar = ColorBar(orientation='vertical',
                          color_mapper=color_mapper,
-                         legend_height=height,
-                         legend_width=width,
+                         height=height,
+                         width=width,
                          ticker=LogTicker(),
                          label_standoff=12)
     return color_bar
@@ -27,8 +27,8 @@ def create_horizontal_color_bar_with_linear_cmap(height='auto', width='auto'):
     color_mapper = LinearColorMapper(low=0, high=100, palette='Spectral10')
     color_bar = ColorBar(orientation='horizontal',
                          color_mapper=color_mapper,
-                         legend_height=height,
-                         legend_width=width)
+                         height=height,
+                         width=width)
     return color_bar
 
 @pytest.mark.screenshot