Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
awesome/tests/examples/wibox/widget/graph/min_value.lua

60 lines
1.7 KiB
Lua
Raw Normal View History

doc: Add examples for the graph.
2021-03-28 11:33:38 +02:00
--DOC_GEN_IMAGE --DOC_HIDE
local parent = ... --DOC_HIDE
local wibox = require("wibox") --DOC_HIDE
local data = { --DOC_HIDE
3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
} --DOC_HIDE
local w1 = --DOC_HIDE
wibox.widget {
max_value = 30,
graph: complete widget overhaul and bug fixes Squashed commit of the following: commit 69821f51fe1e8652715658543e50631ece495090 Author: Alex Belykh <albel727@ngs.ru> Date: Mon May 10 19:17:55 2021 +0700 Refactor property handling in wibox.widget.graph In addition, baseline_value, step_width and step_spacing properties are all set to their default non-nil numeric values during instance creation now. commit 842eb429bf5df4b2ba46b2e6f7646afe89b1a3c3 Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 9 06:18:45 2021 +0700 Make graph:draw_values() private There's no documentation nor confidence that it's a good API, so I'm hiding it for now. commit 720746780574e4bad14a71fc4174955139c2eb50 Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 04:04:13 2021 +0700 Document graph_should_draw_data_group() for posterity commit 7c73f3754ce6ba86b118f1170a6f9e406ab4841d Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 03:59:21 2021 +0700 Make graph:should_draw_data_group() private There's no confidence whether it's a good API, so I'm hiding it for now. commit b3539e20adb6423118af726ae4f8751ef864b5d2 Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 03:36:44 2021 +0700 Make graph:preprocess_values() private There's no confidence whether it's a good API, so I'm hiding it for now. commit 2df4400e780a6260f8d0ab1c60734fbb11bf3c4f Author: Alex Belykh <albel727@ngs.ru> Date: Thu May 6 10:05:23 2021 +0700 Add spec/wibox/widget/graph_spec.lua commit ce01a9771ab439b8df841f1565aa4aa8a44a5e0d Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 08:16:18 2021 +0700 Improve graph.capacity documentation commit e28fade8f655802f5bf89154169f68d256b8e332 Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 07:36:01 2021 +0700 Document graph:compute_drawn_values_num() commit dd68332292465422d08b48e9f0229f143beccbc6 Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 05:24:23 2021 +0700 Document graph:pick_data_group_color() method commit ca6dc55f77aca88a6e9cc90bb6fd0045739f41f5 Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 2 04:13:58 2021 +0700 Guard against setting data groups sparsely in graph:add_value() commit cdea5f126f7984e72924f6dffbd312c4fe3b032f Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 2 02:36:12 2021 +0700 Refactor scaling and baseline choice out of graph:draw() commit 10135deafe8a9390ba66ab657ebb1fb41d549e8c Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 21:34:48 2021 +0700 Document graph.nan_color and graph.stack properties commit 0d73bb84ac66b87e16aee472bd1f299549f66a1c Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 20:49:24 2021 +0700 Use a better example in docs for the graph.stack property commit c27d160a0826d033d49d6141608c40aa8a0642fa Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 16:05:38 2021 +0700 Document graph.baseline_value property commit 459bc8176c13d4ea32af0dcdc2399d3b929b1c6a Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:53:47 2021 +0700 Document graph.clamp_bars property commit e732ee0b3b007d213e689b98cc00ae7cb141ae08 Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:28:34 2021 +0700 Improve graph:add_value() and :clear() documentation commit ae73e3aa9f8d60409cbe4cb4da9612f31af4f38e Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:28:11 2021 +0700 Improve graph min_value/max_value/scale documentation commit a7350996a9def773b91b1631e6c0507e33d8f93b Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:27:36 2021 +0700 Cleanup graph examples to show only relevant things in docs commit 30740c26f4f41c16f4c8a3c339bcb7bd299e14cd Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 14:04:36 2021 +0700 Rename graph.stack_colors property to `group_colors` The colors are used for stacked and non-stacked graphs alike, so the name didn't make sense. Also document and clarify some color stuff. commit 1ea01bfd410971cf0d0c25fd74cd764d5eb7279d Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 21:25:41 2021 +0700 Add an example file for code coverage of some fringe graph cases commit eae68e39553f88a6275a0c65bf040b5d4c262b54 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 20:23:32 2021 +0700 Add step_shape to the graph/nan_color example for code coverage commit 8027147bc2eab34a97b49a428fb8cef27f122bed Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:55:18 2021 +0700 Add example files for graph.nan_color/nan_indication properties commit 89a25a165c52b2c15b6c4d95ecb777a9067e66f9 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:33:07 2021 +0700 Make widget graph:add_value(v) default v to NaN 0 as a default makes no sense and silences the error that is failing to specify a value, to which the user should rather be alerted. The graph widget has sane NaN handling now and will do just that. commit 2835d552440be48d356a7f7b1d64963696dd550b Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:20:48 2021 +0700 Implement graph.nan_color and nan_indication properties Now, whenever there's a NaN among values and graph.nan_indication is set, the corresponding area, where the value bar should have been drawn, is filled with the nan_color from top to bottom. The painting is done after all data is rendered, to make sure that it won't be overpainted and go unnoticed. NaNs among graph's values are inevitably a sign of some error and it is arguably not a sane default behavior to simply not render them at all. The user should take immediate note of any errors by default, instead of wondering at a mysteriously empty graph widget, which is why nan_indication is set to true by default. If the user wants to silence NaNs, they can always simply set it to false. nan_color if unset, defaults to a noticeable yellow-black pattern. As a direct and planned consequence, stacked graphs with negative values in them trigger the NaN handling too. But silencing NaN handling for those graphs is also possible and semi-sane, because then NaNs and negatives are ignored and the graph behaves (almost) like they were zeros. commit 9c1f8f08b400e01e19c534f3810c9c9ab485760c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 26 08:10:19 2021 +0700 Refactor out graph_map_value_to_widget_coordinates() function commit 1905991ddecabdae3e15ffb8ee5b18a1bee1a711 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 28 13:39:29 2021 +0700 Add an example file for graph.baseline_value property commit b31b39d66f4c037a9484b71a3f910703ae01fac0 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 07:03:49 2021 +0700 Add an example file for graph.clamp_bars=false/true comparison commit a1fc850e3047f9ee2c9ddeffacfbabf3ded34171 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 04:06:45 2021 +0700 Add an example file for graphs with negative values and shapes commit 2f012f8ff1bb5094c14e724a61e59a2a3a296bc8 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 01:06:05 2021 +0700 Add an example file for a graph displaying negative values commit 7b14fbd59a4c4c51962fd3110a1a900dd5f4eb98 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 11:18:26 2021 +0700 Add an example file for graphs with step_width < 1 commit dfd9a54544b637e2fbe3d1325f9cc24b3f4d2313 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 10:17:38 2021 +0700 Add an example file for graph.stack=false/true comparison Should also demonstrate that multiple data groups are possible for non-stacked graphs too. commit 5b532106c3fd255f9b66a66cfb88d977b489ab5d Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 09:34:14 2021 +0700 Add an example file for disabling graph data groups with nil colors commit ac6f1083c02fcb428f089a616f9b0ebaa5496b6c Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 08:57:25 2021 +0700 Add an example file for step_shape/width/spacing on stacked graphs commit b3703db6a5139e73e72c1cfd198ece2cd9be7df2 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 08:43:56 2021 +0700 Add an example file for scale=false/true on stacked graph commit b000aed4a12cb44fb501e1c8432a71a14b2f8f3f Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 20 08:22:19 2021 +0700 Document deprecation of graph's width and height commit cb0ad617bd6c83a499896797318e3b0b588c3566 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 19 07:53:37 2021 +0700 Deprecate width and height properties of wibox.widget.graph commit 8c64e14ad91a074b784166a7054e53444cccb9d2 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 19 04:37:59 2021 +0700 Refactor graph:draw() to separate concerns Firstly, summation of group values for stacked graphs is extracted into graph:preprocess_values(). This makes graph:draw() smaller and exposes the fact, that stacked graphs are almost entirely just a form of a more general concept: pre-render data manipulation. It's something a user might want to customize, and now they can do it by monkey-patching the method. Secondly, the logic for deciding, if and with which color a data group should be drawn, is extracted into graph:should_draw_data_group() and get_data_group_color() methods respectively. This makes it customizable too and makes more obvious the fact, that it is a general thing that has nothing to do with stacked graphs in particular. With this there are only 5 lines remaining in graph:draw(), that could be said to be specific to stacked graphs, all pertaining to the `prev_y` variable, which merely preserves the bar coordinates from a previous data group. commit 2a32b6305d893f413303728a0a3da1dcd9a5591e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 22:52:37 2021 +0700 Pointlessly optimize graph:add_value() 1) Purge old values first, then insert the new one, if needed. Since Lua grows arrays in power of two steps, and our guess_capacity() also takes care to return even integers, it would be a shame to overstep the capacity by one by inserting first and thus getting the table size doubled only to never use the most of it. 2) Use a removal procedure that doesn't call the slow length operator at all. Previous code called it twice (once in table.remove) for every removed value. commit 680ea8f5d81e9040afb4662b3229e937e4b89e02 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:23:38 2021 +0700 Set graph data series color before the painting loop commit b970f0f221ae76250f2a94433ff79d653caa6e21 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:05:37 2021 +0700 Drop a large no longer necessary `if` in graph:draw_values() This commit is almost purely a whitespace change. commit 6b4f0541c70ec99d7f6e276bae64939f337120d6 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:00:50 2021 +0700 Extract values rendering code into graph:draw_values() method This is to avoid ungodly if nesting levels, which are needed to bail out of drawing values early and skip to drawing the border. The next commit will get rid of the if. commit e0950e4f99d1ea1c4b8cea2cc67629fa40030c2a Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 14:50:20 2021 +0700 Track graph draw() usage to guess necessary array capacity The last step of divorcing add_values() from width calculations, while ensuring that user doesn't observe a lack of data to draw. The widget now tracks an approximate number of values that it has been asked to draw() in _private.last_drawn_values_num, and truncates its values array based on that (if not overridden by the capacity property). commit 2e3d542282f35e7c0fed454da0f2eada0fcf3b78 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 13:35:12 2021 +0700 Add `capacity` property to graph widget This is the second step of divorcing add_values() from calculations involving widths. How many values are stored and how many values are drawn are distinct concepts. There isn't even a single definitive "how many values are drawn" because the widget could be rendered in several places with distinct widths simultaneously, and in every such place the data must be drawn appropriately, e.g. with auto-scaling, that takes only the visible data points into account. And the draw() method can do that now. The default capacity value of nil uses heuristics based on widget's _private.width to guess some capacity that would tolerate some dynamic widget resizing. If the user finds the heuristic failing them, they can set the capacity property to the desired maximum number of values that will be kept in the _private.values array (in each data group). commit 08d4a80686f7fe363551c35589a460839f60853e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 03:27:18 2021 +0700 Extract values size computation into compute_drawn_values_num() This is the first step of making add_values() not concern itself (directly) with widget dimensions. The user can monkey-patch the method to override how many values are (logically) drawn, because it affects graph auto-scaling and can be useful for rendering of step_shape-s that paint outside of their step_width. I didn't make it a full-blown function-valued property, because it seems a fringe functionality, which I'm too lazy to document. commit 3c5617c98ab1147618ed22e8414a77fc56b45f6e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 02:32:29 2021 +0700 Copy graph widget prototype methods over in bulk commit 169538837ece41a03d02ba8fbc0e4097062b67a3 Author: Alex Belykh <albel727@ngs.ru> Date: Sun Apr 25 05:58:01 2021 +0700 Remove graph.baseline_y property After giving it some thought I've concluded, that it is unlikely to be useful as it is now. I'd better reserve the name for some more sensible functionality, like fixing the baseline_value defined axis at the given widget coordinate, adjusting the scaling accordingly, so min_value/max_value won't generally correspond to widget top and bottom anymore. commit 202ffaa9a0b820c7c471e1121d01b91f8f76cd38 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 12:06:55 2021 +0700 Add baseline_y and baseline_value properties to graph widget Now values in graph have a *baseline*, tunable with baseline_y and baseline_value properties. It is the (for now invisible) horizontal line from which all bars in the graph grow. I call it a "baseline" instead of "axis", because it doesn't actually have to correspond to the 0 value. But it can, and actually does now by default. baseline_y and baseline_value properties determine the vertical placement of the baseline in the widget. baseline_y is the position of the baseline in normalized widget coordinates, e.g. 0 corresponds to widget's top, 1 - to widget's bottom, and 0.5 - to widget's middle. So if e.g. one sets baseline_y = 0, then no matter how the widget is resized and how its values are scaled, bars in it will be drawn starting from the top. baseline_value is the position of the baseline in value coordinates. So if one sets baseline_value = 10, then no matter what happens, bars for values greater than 10 will be drawn as growing up from this line, and bars for values smaller as growing down. Where and if it will be seen in the widget, depends on the scaling. baseline_value = 0 is the familiar zero axis. baseline_y is unset by default and has priority, i.e. if it's set, then baseline_value is ignored. baseline_value defaults to 0. Prior to this commit, bars were always drawn from the bottom edge of the widget, or, in the new terms, the widget had baseline_y = 1. But it was indistinguishable from baseline_value = 0, because the widget clamped all negative values to 0, so the difference between the two could never be observed. baseline_value = 0 is clearly more useful and familiar to people, so now it is in force by default. commit df7e19abaebf0a871b5ca217b4cc3365533267a6 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 11:18:12 2021 +0700 Move value clamping from graph:add_value() into draw() Previously all values were forcibly clamped between 0 (not tunable at all) and max_value (1 by default). Thus graphs with negative values were not an option. NaN values were conflated with zeros, even though it may be useful to maintain the distinction and render them differently. And if user happened to dynamically change the max_value property, they discovered, that their data got truncated. Preserving user data as it was given is more flexible and makes things easier to debug. This commit does exactly that. So what happens now to the newly allowed values during draw()? There are 3 new cases to consider: 1) NaNs 2) Negatives 3) Values outside of min_value..max_value range NaNs are presently simply not drawn. An empty place is reserved where the value should've been, but nothing else is done. This is distinct from how a zero is handled, e.g. if step_shape is set, it is called with the height parameter = 0, which can still end up drawing something, depending on the shape. One could also consider addition of nan_color/nan_shape properties which could be drawn to alert user to a gap in their data. Negative values necessitate introduction of the concept of the zero axis, from which they will be drawn DOWN, in contrast to positive values. Where should this axis be drawn? How should step_shape-s with inherent direction, e.g. arrows, be drawn for negatives? This will be addressed in the next commit. Values outside of min/max_value range can imply shapes that go beyond widget dimensions. An arrow shape that goes beyond the roof is visibly different from an arrow that saturates and merely touches the widget top, and the user may reasonably desire either behavior. Therefore this commit introduces a boolean clamp_bars property, which defaults to true for reasons of robustness and backward compatibility with the behaviour prior to this commit. The property of course affects only the display of the values, the actual user data stays intact. commit c9c24fb1ab741cd6bb8074971d568e0646c51532 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 09:29:01 2021 +0700 Use rectangles for drawing graph bars of all sizes I have benchmarked various bar drawing strategies and graph sizes and found out that drawing graph bars with rectangles is as fast or even marginally faster than using fat lines. Thus the code that tries to special-case 1px bars as lines seems to be not worth the additional complexity it introduces, and this commit removes it. Incidentally, I've also established, that rectangles are more robust. If one draws graph bars and feeds cairo very large coordinates (~2^62), then corresponding rectangles fail to render, but all the other rectangles in the same series get rendered successfully, whereas a single large coordinate in a move_to/line_to() sequence is enough to cause all lines in the batch to fail to render. commit bc7f4be5e06405b5aa7fb443a5ace2b9b9575b1f Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 09:01:42 2021 +0700 Cache cairo methods used in the inner loop of graph:draw() I have benchmarked the draw() method, both on cairo xcb and on argb32 image surfaces, and have discovered that cairo context method calls are unnaturally slow, to the point, that almost nothing else in the function matters. For example, drawing bars with vertical lines made the whole draw() function almost 2 times slower than doing the same with rectangles, merely because the former requires two method calls (move_to/line_to), and the latter only one. Simply caching hotpath cairo methods in local variables, reduced the difference between the drawing methods to a negligible one and made the whole function 4 times faster on a typical 100-bar graph, (1.4ms to 0.33ms on my laptop) thus bringing closer my secret dream of drawing live audio data with awesome graphs (kidding). I guess, LGI does something not very optimal there, like gobject-introspecting the method every time, or something. There might be some untapped optimization potential, possibly in upstream, like a method cache, from which everything in awesome could benefit, even though I imagine not many things are so call-intensive as the graph widget, to really feel the difference. commit 538df25bdf02b53d0bbe81809eef2e6fdb05ff6f Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 07:32:37 2021 +0700 Use 1-based index in the inner graph draw loop It's used there only once for a calculation and then several times to index some tables, and index 0 is bad for lua tables performance-wise. commit 7412546916cd0a0a490130a120255ffb719398b8 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 21:55:12 2021 +0700 Leave graph.max_value uninitialized at construction This is a user-visible change, but the previous behavior was probably not what user expected anyway, namely with graph.scale set the graph mysteriously couldn't zoom in onto values that are smaller than 1. commit eb81d7929a161e79c13262cfa73ac2e6a820e8ed Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 21:48:29 2021 +0700 Allow graph.max_value be nil This makes its behave symmetrically to min_value. Now it defaults to 1, when graph.scale is not set, and to the maximum value in the graph data, when graph.scale is set. commit f622a8430cbfde7007b58d7f4c9c76b08c91e997 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 12:01:13 2021 +0700 Calculate max values num in graph:add_value() more precisely At most so many values were kept in the widget values array, as there are pixels of usable widget width (i.e. sans border). This is exactly right for the surely most common case of graphs with 1px-wide bars, but is more than needed for graphs with step_width+step_spacing>1, and not enough for graphs with subpixel bars. Moreover this made graph autoscaling behave weirdly in graphs with thicker bars, because old values survived longer in the array and kept affecting min_value/max_value calculations even after they were shifted off-screen. The maximum number of kept values is now calculated exactly as the number of values that can be displayed at once, taking step_width and step_spacing into account. It might be worth adding a max_values_num property to the graph to let user override this calculation, in case they draw shapes in step_shape() outside of its supposed rectangle, so our assumptions of visibility are wrong, or the widget often gets resized, resulting in the annoyance of visibly truncated series. commit 0aa63249a18641251a1bf77423739164f0eab39f Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 02:30:13 2021 +0700 Fix border_color/border_width bugs in graph widget add_value() wrongly assumed that border_width is always set, when border_color is, so if user set only the latter, an error occurred. add_value() assumed that border_width is always < width which led to awesome hanging up in an infinite loop, should that fail to be the case. The graph border_width property was driven by the border_color property, instead of the other way round. If border_color wasn't set, the border wasn't drawn all, even if user sets non-zero border_width, which is a confusing behavior, in contrast to all other widgets, which simply use a plethora of fallback colors to draw the border, when needed. This also meant that, despite being documented, the beautiful.graph_border_color fallback color could not and was not ever used. If the border_color was set though, an unset border_width was immediately assumed to be 1 instead of 0, also contrary to what other widgets do. Theme colors shouldn't influence widget layout, so this commit fixes this behavior to: 1) border_width always defaults to 0, if unset. 2) border_color falls back to beautiful.graph_border_color or white. Maybe one should also add a beautiful.graph_border_width theme variable, like some widgets do. commit dad4a3253b8fef971fb82720d2a407fcc0a879ad Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 14 03:11:27 2021 +0700 Implement multiple data series drawing for non-stacked graph The widget can already hold and draw multiple data groups, so it makes little sense to limit drawing only to the first group when graph.stack = false, probably leading to user's confusion. Now user can call add_value(v, group) with group > 1 and the data series will be drawn (over groups with lesser id-s) with graph.stack_colors[group] color, if stack_colors is set, or with graph.color, if stack_colors isn't set. Thus nothing visibly changes for all current users of non-stacked graphs with only single data series, but the new functionality is now there for those who need it. One can't fully emulate this functionality, e.g. with multiple graphs widgets in a wibox.layout.stack, because data series in a single widget can enjoy a common auto-scaling. commit 3e645c976184ab5f50d625271c25062db9ab7ed9 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 01:59:12 2021 +0700 Don't draw a stacked graph data group if there's no color for it If stack_colors[idx] is nil for the group `idx`, don't draw it at all (as opposed, e.g. to the effect of drawing it with a transparent color, or as though it had all values == 0, which both produce different results). This code is still subtly different from prior behavior, because now user can have a non-contiguous stack_colors table and turn the display of any data group on and off at will, whereas the code two commits earlier would just stop rendering as soon as ipairs(stack_colors) does, i.e. no data series were drawn past the first nil hole. This commit only looks large, but is mostly a whitespace change due to nesting from a pair of wrapping ifs. commit 8c0273786de1ade66bdd977699f98b588da9f487 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 01:32:42 2021 +0700 Unify stacked and non-stacked graph rendering Now stacked graphs support everything the nonstacked do, like step_width ~= 1 and custom step_shape-s. Technical notes: This code no longer calls cr:stroke() for every single value in a stacked graph, but rather paints a whole series and then cr:stroke/fill()-s it at all once with its color, improving performance considerably. Additionally the graph no longer relies on the presence of the stack_colors property to render series. It draws all data that it has, and, if there's no corresponding color in stack_colors, falls back to graph.color. This will be changed in the next commit to the prior behavior of only drawing those series for which there's a color in the stack_colors table, but that would've made this commit's diff much larger due to required nesting ifs over large code chunks. This commit also takes care to properly handle NaNs and negative values. Those are currently (almost) guaranteed to not occur in the values array due to clipping in graph:add_value(), but I intend to eventually drop the clipping, because it does nothing that draw() really relies upon, and allowing unclipped and NaN values is more flexible and less surprising, e.g. when user dynamically toggles graph.scale. Eventually I intend to implement drawing negative values in non-stacked graphs and possibly even in the stacked ones. commit 38c6589c51b2aa057d7c2f40182ecf32b5b2ff5e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 10:04:15 2021 +0700 Convert graph:draw() to use `self` commit f21f1b2550426df1c4ea8abde079b1ccef84b394 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 12:27:26 2021 +0700 Fix scaling for stacked graphs Stacked graphs have cumulative heights, values from all groups that end up in the same graph bar are effectively summed. Previous code didn't take that into account when calculating min/max_value for the purposes of rescaling, but simply examined every value separately. This code adds up all values up front and finds min/max among those, to determine proper scaling that would fit the graph exactly. commit 1ce4c7bf63bdd6c99c195d668347bec49355e921 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 09:49:35 2021 +0700 Draw shaped graph bars only up to the baseline Prior to this commit, every step_shape bar was, for some reason, drawn with height = full widget's height, regardless of the value it represents. So for the most bars their lower end was far outside the box and therefore clipped off. So e.g. one couldn't see the lower round edges of rounded rectangles. This commit fixes that by appropriately varying the height that is passed into step_shape(), so that lower edges of the bars always exactly touch the lower edge of the graph. If the user wants to restore the prior behavior, they can simply ignore the passed-in height in step_shape() and just always draw their shape with height = full widget height. But they couldn't replicate the effect of this commit in their rc.lua without essentially writing their own graph widget. commit e25185b08da23745b5815f85f6e9e43222ed2294 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 08:42:54 2021 +0700 Avoid incremental transform shifting during graph bar rendering Instead of letting addition errors and cognitive load accumulate simply use the same offset calculation that is used for lines and reset the transform back to the top-left corner after every drawn bar. It's conceptually simpler, and will be useful later for stacked graphs and more. It also fixes a discrepancy between plain and step_shape rendering. Prior to this commit, bar coloring occurred with a disturbed transform, which was centered at the last drawn bar, wherever it happened to be. This meant that nontrivial colors, like gradients and images, were arbitrarily offset when step_shape was used. commit f3e98866d8583c35d0b557c09f529299edc9ba2c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 06:45:29 2021 +0700 Refactor out graph bar height expression into a variable commit f54528d6892f5aaa4595917853c9e2130f743fdb Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 06:20:25 2021 +0700 Draw graph bars with lines only when step_width == 1 Before this commit graph bars of step_width < 1 were drawn with lines of width 1, but that's a bit unfortunate, because it led to much overpainting, while still ending up with a graphically incorrect result. Let's draw such bars with rectangles and let cairo do things with subpixels, getting more graphically accurate result, while still keeping the common case of step_width == 1 (supposedly) fast-drawn with lines. commit b6515dca67c18b78eb5657378131a62ab43d4cfc Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:54:07 2021 +0700 Fix unsharp edges when drawing graph bars with rectangles The 0.5 offset is only helpful for 1-width strokes, not for fills. commit 7f3db8f07e82f821bcd1dc418d66564f537609d6 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:21:01 2021 +0700 Do coordinate transformations even if the value isn't drawn The graph presently doesn't draw values < 0, but there was a discrepancy between drawing with and without step_shape. The default line/rectangle drawing reserves an empty place where the skipped value should've been, but no such empty place is reserved, when step_shape is used. This commit fixes that. Skipped values always have their empty space now. commit 7b731ebfe96af7a9dba9c57371da6761cf22c00c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:03:30 2021 +0700 Fix graph bar scaling when min_value is not 0 Previous calculation lead to underscaling of values so that even value = max_value wasn't drawn to full height. commit dca59fd8b7fff0e7e646f2dfc6bd92047028e5a8 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:18:40 2021 +0700 Calculate the horizontal graph bar offset only when needed commit 940ddf4b9825e9c3a91d276208c089d8c74e49db Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:17:23 2021 +0700 Call cr:move_to() only when drawing the graph with lines It's redundant otherwise and might even interfere with user's drawing in step_shape(). commit b5d5cd10ca29fb29cd751faaa95137c2fe89ff63 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:04:06 2021 +0700 Fix wrong horizontal offset calculations in widget.graph Indices in the loop are zero-based, so things like i-1 and i>1 aren't necessary and actually wouldn't have been correct even in a 1-based loop. step_shape = gears.shape.rectangle and step_shape = nil, which is supposed to default to rectangle according to docs, were drawn differently due to mismatched offset calculations, which led to problems especially noticeable when step_spacing is not zero, e.g: 1) whole graph shifted left too much, drawn partially off-screen. 2) whole graph shifted right too much, and the first bar placed closer to the rest than others. commit dc369fa198281e000afc1bd17326f3a264adf7d1 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 02:09:21 2021 +0700 Fix the "border_width affects graph bar width" bug Graph bars were drawn with lines of border_width thickness instead of 1, i.e. possibly too fat to be readable. commit 1ba73378cf29ed27a6ecd18716394779ceb543d9 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 14 00:13:03 2021 +0700 Simplify internal values representation in graph even more New values in graph._private.values were pushed to the end, and old values were removed from the beginning of the table. In draw() however newer values are drawn first, at the left edge of the graph, necessitating annoying idx = #values - idx conversions everywhere. In particular in stacked graph that means that values that are drawn together may have different indices. One has to shift the values array in add_value() either way, so one might as well insert new values at the beginning of the array and simplify the rest of the code. This doesn't seem like much yet, but it will prove to be much more convenient and less error-prone in what I'm going to do later. commit f70523ee68dbd6b67050ace4b82903a9b22440c7 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 13:35:10 2021 +0700 Simplify internal values representation in graph widget graph._private.values was either a table of values or a table of tables of values, depending on whether "stack" property is enabled, ... or a mix of both if user forgot to pass the second "group" parameter to graph:add_value(). This resulted in pretty fragile and confusing behavior, e.g. leaving user to wonder, why they see nothing more after setting stack=true for a graph in a previously working rc.lua, and demanding a very careful use of add_value() from the user, or else some values or even entire stacks would mysteriously vanish and errors in draw() get triggered, sometimes after a period of seemingly normal functioning. Now `values` is always a table of tables and the group parameter in add_value() defaults to 1, thus making the non-stacked graph a trivial variant of the stacked graph.
2021-05-20 17:14:03 +02:00
forced_height = 20, --DOC_HIDE
doc: Add examples for the graph.
2021-03-28 11:33:38 +02:00
widget = wibox.widget.graph,
}
--DOC_NEWLINE
local w2 = --DOC_HIDE
wibox.widget {
min_value = 10,
max_value = 30,
graph: complete widget overhaul and bug fixes Squashed commit of the following: commit 69821f51fe1e8652715658543e50631ece495090 Author: Alex Belykh <albel727@ngs.ru> Date: Mon May 10 19:17:55 2021 +0700 Refactor property handling in wibox.widget.graph In addition, baseline_value, step_width and step_spacing properties are all set to their default non-nil numeric values during instance creation now. commit 842eb429bf5df4b2ba46b2e6f7646afe89b1a3c3 Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 9 06:18:45 2021 +0700 Make graph:draw_values() private There's no documentation nor confidence that it's a good API, so I'm hiding it for now. commit 720746780574e4bad14a71fc4174955139c2eb50 Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 04:04:13 2021 +0700 Document graph_should_draw_data_group() for posterity commit 7c73f3754ce6ba86b118f1170a6f9e406ab4841d Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 03:59:21 2021 +0700 Make graph:should_draw_data_group() private There's no confidence whether it's a good API, so I'm hiding it for now. commit b3539e20adb6423118af726ae4f8751ef864b5d2 Author: Alex Belykh <albel727@ngs.ru> Date: Fri May 7 03:36:44 2021 +0700 Make graph:preprocess_values() private There's no confidence whether it's a good API, so I'm hiding it for now. commit 2df4400e780a6260f8d0ab1c60734fbb11bf3c4f Author: Alex Belykh <albel727@ngs.ru> Date: Thu May 6 10:05:23 2021 +0700 Add spec/wibox/widget/graph_spec.lua commit ce01a9771ab439b8df841f1565aa4aa8a44a5e0d Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 08:16:18 2021 +0700 Improve graph.capacity documentation commit e28fade8f655802f5bf89154169f68d256b8e332 Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 07:36:01 2021 +0700 Document graph:compute_drawn_values_num() commit dd68332292465422d08b48e9f0229f143beccbc6 Author: Alex Belykh <albel727@ngs.ru> Date: Wed May 5 05:24:23 2021 +0700 Document graph:pick_data_group_color() method commit ca6dc55f77aca88a6e9cc90bb6fd0045739f41f5 Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 2 04:13:58 2021 +0700 Guard against setting data groups sparsely in graph:add_value() commit cdea5f126f7984e72924f6dffbd312c4fe3b032f Author: Alex Belykh <albel727@ngs.ru> Date: Sun May 2 02:36:12 2021 +0700 Refactor scaling and baseline choice out of graph:draw() commit 10135deafe8a9390ba66ab657ebb1fb41d549e8c Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 21:34:48 2021 +0700 Document graph.nan_color and graph.stack properties commit 0d73bb84ac66b87e16aee472bd1f299549f66a1c Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 20:49:24 2021 +0700 Use a better example in docs for the graph.stack property commit c27d160a0826d033d49d6141608c40aa8a0642fa Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 16:05:38 2021 +0700 Document graph.baseline_value property commit 459bc8176c13d4ea32af0dcdc2399d3b929b1c6a Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:53:47 2021 +0700 Document graph.clamp_bars property commit e732ee0b3b007d213e689b98cc00ae7cb141ae08 Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:28:34 2021 +0700 Improve graph:add_value() and :clear() documentation commit ae73e3aa9f8d60409cbe4cb4da9612f31af4f38e Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:28:11 2021 +0700 Improve graph min_value/max_value/scale documentation commit a7350996a9def773b91b1631e6c0507e33d8f93b Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 15:27:36 2021 +0700 Cleanup graph examples to show only relevant things in docs commit 30740c26f4f41c16f4c8a3c339bcb7bd299e14cd Author: Alex Belykh <albel727@ngs.ru> Date: Sat May 1 14:04:36 2021 +0700 Rename graph.stack_colors property to `group_colors` The colors are used for stacked and non-stacked graphs alike, so the name didn't make sense. Also document and clarify some color stuff. commit 1ea01bfd410971cf0d0c25fd74cd764d5eb7279d Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 21:25:41 2021 +0700 Add an example file for code coverage of some fringe graph cases commit eae68e39553f88a6275a0c65bf040b5d4c262b54 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 20:23:32 2021 +0700 Add step_shape to the graph/nan_color example for code coverage commit 8027147bc2eab34a97b49a428fb8cef27f122bed Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:55:18 2021 +0700 Add example files for graph.nan_color/nan_indication properties commit 89a25a165c52b2c15b6c4d95ecb777a9067e66f9 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:33:07 2021 +0700 Make widget graph:add_value(v) default v to NaN 0 as a default makes no sense and silences the error that is failing to specify a value, to which the user should rather be alerted. The graph widget has sane NaN handling now and will do just that. commit 2835d552440be48d356a7f7b1d64963696dd550b Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 30 19:20:48 2021 +0700 Implement graph.nan_color and nan_indication properties Now, whenever there's a NaN among values and graph.nan_indication is set, the corresponding area, where the value bar should have been drawn, is filled with the nan_color from top to bottom. The painting is done after all data is rendered, to make sure that it won't be overpainted and go unnoticed. NaNs among graph's values are inevitably a sign of some error and it is arguably not a sane default behavior to simply not render them at all. The user should take immediate note of any errors by default, instead of wondering at a mysteriously empty graph widget, which is why nan_indication is set to true by default. If the user wants to silence NaNs, they can always simply set it to false. nan_color if unset, defaults to a noticeable yellow-black pattern. As a direct and planned consequence, stacked graphs with negative values in them trigger the NaN handling too. But silencing NaN handling for those graphs is also possible and semi-sane, because then NaNs and negatives are ignored and the graph behaves (almost) like they were zeros. commit 9c1f8f08b400e01e19c534f3810c9c9ab485760c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 26 08:10:19 2021 +0700 Refactor out graph_map_value_to_widget_coordinates() function commit 1905991ddecabdae3e15ffb8ee5b18a1bee1a711 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 28 13:39:29 2021 +0700 Add an example file for graph.baseline_value property commit b31b39d66f4c037a9484b71a3f910703ae01fac0 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 07:03:49 2021 +0700 Add an example file for graph.clamp_bars=false/true comparison commit a1fc850e3047f9ee2c9ddeffacfbabf3ded34171 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 04:06:45 2021 +0700 Add an example file for graphs with negative values and shapes commit 2f012f8ff1bb5094c14e724a61e59a2a3a296bc8 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 22 01:06:05 2021 +0700 Add an example file for a graph displaying negative values commit 7b14fbd59a4c4c51962fd3110a1a900dd5f4eb98 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 11:18:26 2021 +0700 Add an example file for graphs with step_width < 1 commit dfd9a54544b637e2fbe3d1325f9cc24b3f4d2313 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 10:17:38 2021 +0700 Add an example file for graph.stack=false/true comparison Should also demonstrate that multiple data groups are possible for non-stacked graphs too. commit 5b532106c3fd255f9b66a66cfb88d977b489ab5d Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 09:34:14 2021 +0700 Add an example file for disabling graph data groups with nil colors commit ac6f1083c02fcb428f089a616f9b0ebaa5496b6c Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 08:57:25 2021 +0700 Add an example file for step_shape/width/spacing on stacked graphs commit b3703db6a5139e73e72c1cfd198ece2cd9be7df2 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 21 08:43:56 2021 +0700 Add an example file for scale=false/true on stacked graph commit b000aed4a12cb44fb501e1c8432a71a14b2f8f3f Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 20 08:22:19 2021 +0700 Document deprecation of graph's width and height commit cb0ad617bd6c83a499896797318e3b0b588c3566 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 19 07:53:37 2021 +0700 Deprecate width and height properties of wibox.widget.graph commit 8c64e14ad91a074b784166a7054e53444cccb9d2 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 19 04:37:59 2021 +0700 Refactor graph:draw() to separate concerns Firstly, summation of group values for stacked graphs is extracted into graph:preprocess_values(). This makes graph:draw() smaller and exposes the fact, that stacked graphs are almost entirely just a form of a more general concept: pre-render data manipulation. It's something a user might want to customize, and now they can do it by monkey-patching the method. Secondly, the logic for deciding, if and with which color a data group should be drawn, is extracted into graph:should_draw_data_group() and get_data_group_color() methods respectively. This makes it customizable too and makes more obvious the fact, that it is a general thing that has nothing to do with stacked graphs in particular. With this there are only 5 lines remaining in graph:draw(), that could be said to be specific to stacked graphs, all pertaining to the `prev_y` variable, which merely preserves the bar coordinates from a previous data group. commit 2a32b6305d893f413303728a0a3da1dcd9a5591e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 22:52:37 2021 +0700 Pointlessly optimize graph:add_value() 1) Purge old values first, then insert the new one, if needed. Since Lua grows arrays in power of two steps, and our guess_capacity() also takes care to return even integers, it would be a shame to overstep the capacity by one by inserting first and thus getting the table size doubled only to never use the most of it. 2) Use a removal procedure that doesn't call the slow length operator at all. Previous code called it twice (once in table.remove) for every removed value. commit 680ea8f5d81e9040afb4662b3229e937e4b89e02 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:23:38 2021 +0700 Set graph data series color before the painting loop commit b970f0f221ae76250f2a94433ff79d653caa6e21 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:05:37 2021 +0700 Drop a large no longer necessary `if` in graph:draw_values() This commit is almost purely a whitespace change. commit 6b4f0541c70ec99d7f6e276bae64939f337120d6 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 16:00:50 2021 +0700 Extract values rendering code into graph:draw_values() method This is to avoid ungodly if nesting levels, which are needed to bail out of drawing values early and skip to drawing the border. The next commit will get rid of the if. commit e0950e4f99d1ea1c4b8cea2cc67629fa40030c2a Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 14:50:20 2021 +0700 Track graph draw() usage to guess necessary array capacity The last step of divorcing add_values() from width calculations, while ensuring that user doesn't observe a lack of data to draw. The widget now tracks an approximate number of values that it has been asked to draw() in _private.last_drawn_values_num, and truncates its values array based on that (if not overridden by the capacity property). commit 2e3d542282f35e7c0fed454da0f2eada0fcf3b78 Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 13:35:12 2021 +0700 Add `capacity` property to graph widget This is the second step of divorcing add_values() from calculations involving widths. How many values are stored and how many values are drawn are distinct concepts. There isn't even a single definitive "how many values are drawn" because the widget could be rendered in several places with distinct widths simultaneously, and in every such place the data must be drawn appropriately, e.g. with auto-scaling, that takes only the visible data points into account. And the draw() method can do that now. The default capacity value of nil uses heuristics based on widget's _private.width to guess some capacity that would tolerate some dynamic widget resizing. If the user finds the heuristic failing them, they can set the capacity property to the desired maximum number of values that will be kept in the _private.values array (in each data group). commit 08d4a80686f7fe363551c35589a460839f60853e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 03:27:18 2021 +0700 Extract values size computation into compute_drawn_values_num() This is the first step of making add_values() not concern itself (directly) with widget dimensions. The user can monkey-patch the method to override how many values are (logically) drawn, because it affects graph auto-scaling and can be useful for rendering of step_shape-s that paint outside of their step_width. I didn't make it a full-blown function-valued property, because it seems a fringe functionality, which I'm too lazy to document. commit 3c5617c98ab1147618ed22e8414a77fc56b45f6e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 02:32:29 2021 +0700 Copy graph widget prototype methods over in bulk commit 169538837ece41a03d02ba8fbc0e4097062b67a3 Author: Alex Belykh <albel727@ngs.ru> Date: Sun Apr 25 05:58:01 2021 +0700 Remove graph.baseline_y property After giving it some thought I've concluded, that it is unlikely to be useful as it is now. I'd better reserve the name for some more sensible functionality, like fixing the baseline_value defined axis at the given widget coordinate, adjusting the scaling accordingly, so min_value/max_value won't generally correspond to widget top and bottom anymore. commit 202ffaa9a0b820c7c471e1121d01b91f8f76cd38 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 12:06:55 2021 +0700 Add baseline_y and baseline_value properties to graph widget Now values in graph have a *baseline*, tunable with baseline_y and baseline_value properties. It is the (for now invisible) horizontal line from which all bars in the graph grow. I call it a "baseline" instead of "axis", because it doesn't actually have to correspond to the 0 value. But it can, and actually does now by default. baseline_y and baseline_value properties determine the vertical placement of the baseline in the widget. baseline_y is the position of the baseline in normalized widget coordinates, e.g. 0 corresponds to widget's top, 1 - to widget's bottom, and 0.5 - to widget's middle. So if e.g. one sets baseline_y = 0, then no matter how the widget is resized and how its values are scaled, bars in it will be drawn starting from the top. baseline_value is the position of the baseline in value coordinates. So if one sets baseline_value = 10, then no matter what happens, bars for values greater than 10 will be drawn as growing up from this line, and bars for values smaller as growing down. Where and if it will be seen in the widget, depends on the scaling. baseline_value = 0 is the familiar zero axis. baseline_y is unset by default and has priority, i.e. if it's set, then baseline_value is ignored. baseline_value defaults to 0. Prior to this commit, bars were always drawn from the bottom edge of the widget, or, in the new terms, the widget had baseline_y = 1. But it was indistinguishable from baseline_value = 0, because the widget clamped all negative values to 0, so the difference between the two could never be observed. baseline_value = 0 is clearly more useful and familiar to people, so now it is in force by default. commit df7e19abaebf0a871b5ca217b4cc3365533267a6 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 11:18:12 2021 +0700 Move value clamping from graph:add_value() into draw() Previously all values were forcibly clamped between 0 (not tunable at all) and max_value (1 by default). Thus graphs with negative values were not an option. NaN values were conflated with zeros, even though it may be useful to maintain the distinction and render them differently. And if user happened to dynamically change the max_value property, they discovered, that their data got truncated. Preserving user data as it was given is more flexible and makes things easier to debug. This commit does exactly that. So what happens now to the newly allowed values during draw()? There are 3 new cases to consider: 1) NaNs 2) Negatives 3) Values outside of min_value..max_value range NaNs are presently simply not drawn. An empty place is reserved where the value should've been, but nothing else is done. This is distinct from how a zero is handled, e.g. if step_shape is set, it is called with the height parameter = 0, which can still end up drawing something, depending on the shape. One could also consider addition of nan_color/nan_shape properties which could be drawn to alert user to a gap in their data. Negative values necessitate introduction of the concept of the zero axis, from which they will be drawn DOWN, in contrast to positive values. Where should this axis be drawn? How should step_shape-s with inherent direction, e.g. arrows, be drawn for negatives? This will be addressed in the next commit. Values outside of min/max_value range can imply shapes that go beyond widget dimensions. An arrow shape that goes beyond the roof is visibly different from an arrow that saturates and merely touches the widget top, and the user may reasonably desire either behavior. Therefore this commit introduces a boolean clamp_bars property, which defaults to true for reasons of robustness and backward compatibility with the behaviour prior to this commit. The property of course affects only the display of the values, the actual user data stays intact. commit c9c24fb1ab741cd6bb8074971d568e0646c51532 Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 09:29:01 2021 +0700 Use rectangles for drawing graph bars of all sizes I have benchmarked various bar drawing strategies and graph sizes and found out that drawing graph bars with rectangles is as fast or even marginally faster than using fat lines. Thus the code that tries to special-case 1px bars as lines seems to be not worth the additional complexity it introduces, and this commit removes it. Incidentally, I've also established, that rectangles are more robust. If one draws graph bars and feeds cairo very large coordinates (~2^62), then corresponding rectangles fail to render, but all the other rectangles in the same series get rendered successfully, whereas a single large coordinate in a move_to/line_to() sequence is enough to cause all lines in the batch to fail to render. commit bc7f4be5e06405b5aa7fb443a5ace2b9b9575b1f Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 09:01:42 2021 +0700 Cache cairo methods used in the inner loop of graph:draw() I have benchmarked the draw() method, both on cairo xcb and on argb32 image surfaces, and have discovered that cairo context method calls are unnaturally slow, to the point, that almost nothing else in the function matters. For example, drawing bars with vertical lines made the whole draw() function almost 2 times slower than doing the same with rectangles, merely because the former requires two method calls (move_to/line_to), and the latter only one. Simply caching hotpath cairo methods in local variables, reduced the difference between the drawing methods to a negligible one and made the whole function 4 times faster on a typical 100-bar graph, (1.4ms to 0.33ms on my laptop) thus bringing closer my secret dream of drawing live audio data with awesome graphs (kidding). I guess, LGI does something not very optimal there, like gobject-introspecting the method every time, or something. There might be some untapped optimization potential, possibly in upstream, like a method cache, from which everything in awesome could benefit, even though I imagine not many things are so call-intensive as the graph widget, to really feel the difference. commit 538df25bdf02b53d0bbe81809eef2e6fdb05ff6f Author: Alex Belykh <albel727@ngs.ru> Date: Thu Apr 15 07:32:37 2021 +0700 Use 1-based index in the inner graph draw loop It's used there only once for a calculation and then several times to index some tables, and index 0 is bad for lua tables performance-wise. commit 7412546916cd0a0a490130a120255ffb719398b8 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 21:55:12 2021 +0700 Leave graph.max_value uninitialized at construction This is a user-visible change, but the previous behavior was probably not what user expected anyway, namely with graph.scale set the graph mysteriously couldn't zoom in onto values that are smaller than 1. commit eb81d7929a161e79c13262cfa73ac2e6a820e8ed Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 21:48:29 2021 +0700 Allow graph.max_value be nil This makes its behave symmetrically to min_value. Now it defaults to 1, when graph.scale is not set, and to the maximum value in the graph data, when graph.scale is set. commit f622a8430cbfde7007b58d7f4c9c76b08c91e997 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 12:01:13 2021 +0700 Calculate max values num in graph:add_value() more precisely At most so many values were kept in the widget values array, as there are pixels of usable widget width (i.e. sans border). This is exactly right for the surely most common case of graphs with 1px-wide bars, but is more than needed for graphs with step_width+step_spacing>1, and not enough for graphs with subpixel bars. Moreover this made graph autoscaling behave weirdly in graphs with thicker bars, because old values survived longer in the array and kept affecting min_value/max_value calculations even after they were shifted off-screen. The maximum number of kept values is now calculated exactly as the number of values that can be displayed at once, taking step_width and step_spacing into account. It might be worth adding a max_values_num property to the graph to let user override this calculation, in case they draw shapes in step_shape() outside of its supposed rectangle, so our assumptions of visibility are wrong, or the widget often gets resized, resulting in the annoyance of visibly truncated series. commit 0aa63249a18641251a1bf77423739164f0eab39f Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 02:30:13 2021 +0700 Fix border_color/border_width bugs in graph widget add_value() wrongly assumed that border_width is always set, when border_color is, so if user set only the latter, an error occurred. add_value() assumed that border_width is always < width which led to awesome hanging up in an infinite loop, should that fail to be the case. The graph border_width property was driven by the border_color property, instead of the other way round. If border_color wasn't set, the border wasn't drawn all, even if user sets non-zero border_width, which is a confusing behavior, in contrast to all other widgets, which simply use a plethora of fallback colors to draw the border, when needed. This also meant that, despite being documented, the beautiful.graph_border_color fallback color could not and was not ever used. If the border_color was set though, an unset border_width was immediately assumed to be 1 instead of 0, also contrary to what other widgets do. Theme colors shouldn't influence widget layout, so this commit fixes this behavior to: 1) border_width always defaults to 0, if unset. 2) border_color falls back to beautiful.graph_border_color or white. Maybe one should also add a beautiful.graph_border_width theme variable, like some widgets do. commit dad4a3253b8fef971fb82720d2a407fcc0a879ad Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 14 03:11:27 2021 +0700 Implement multiple data series drawing for non-stacked graph The widget can already hold and draw multiple data groups, so it makes little sense to limit drawing only to the first group when graph.stack = false, probably leading to user's confusion. Now user can call add_value(v, group) with group > 1 and the data series will be drawn (over groups with lesser id-s) with graph.stack_colors[group] color, if stack_colors is set, or with graph.color, if stack_colors isn't set. Thus nothing visibly changes for all current users of non-stacked graphs with only single data series, but the new functionality is now there for those who need it. One can't fully emulate this functionality, e.g. with multiple graphs widgets in a wibox.layout.stack, because data series in a single widget can enjoy a common auto-scaling. commit 3e645c976184ab5f50d625271c25062db9ab7ed9 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 01:59:12 2021 +0700 Don't draw a stacked graph data group if there's no color for it If stack_colors[idx] is nil for the group `idx`, don't draw it at all (as opposed, e.g. to the effect of drawing it with a transparent color, or as though it had all values == 0, which both produce different results). This code is still subtly different from prior behavior, because now user can have a non-contiguous stack_colors table and turn the display of any data group on and off at will, whereas the code two commits earlier would just stop rendering as soon as ipairs(stack_colors) does, i.e. no data series were drawn past the first nil hole. This commit only looks large, but is mostly a whitespace change due to nesting from a pair of wrapping ifs. commit 8c0273786de1ade66bdd977699f98b588da9f487 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 01:32:42 2021 +0700 Unify stacked and non-stacked graph rendering Now stacked graphs support everything the nonstacked do, like step_width ~= 1 and custom step_shape-s. Technical notes: This code no longer calls cr:stroke() for every single value in a stacked graph, but rather paints a whole series and then cr:stroke/fill()-s it at all once with its color, improving performance considerably. Additionally the graph no longer relies on the presence of the stack_colors property to render series. It draws all data that it has, and, if there's no corresponding color in stack_colors, falls back to graph.color. This will be changed in the next commit to the prior behavior of only drawing those series for which there's a color in the stack_colors table, but that would've made this commit's diff much larger due to required nesting ifs over large code chunks. This commit also takes care to properly handle NaNs and negative values. Those are currently (almost) guaranteed to not occur in the values array due to clipping in graph:add_value(), but I intend to eventually drop the clipping, because it does nothing that draw() really relies upon, and allowing unclipped and NaN values is more flexible and less surprising, e.g. when user dynamically toggles graph.scale. Eventually I intend to implement drawing negative values in non-stacked graphs and possibly even in the stacked ones. commit 38c6589c51b2aa057d7c2f40182ecf32b5b2ff5e Author: Alex Belykh <albel727@ngs.ru> Date: Fri Apr 16 10:04:15 2021 +0700 Convert graph:draw() to use `self` commit f21f1b2550426df1c4ea8abde079b1ccef84b394 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 12:27:26 2021 +0700 Fix scaling for stacked graphs Stacked graphs have cumulative heights, values from all groups that end up in the same graph bar are effectively summed. Previous code didn't take that into account when calculating min/max_value for the purposes of rescaling, but simply examined every value separately. This code adds up all values up front and finds min/max among those, to determine proper scaling that would fit the graph exactly. commit 1ce4c7bf63bdd6c99c195d668347bec49355e921 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 09:49:35 2021 +0700 Draw shaped graph bars only up to the baseline Prior to this commit, every step_shape bar was, for some reason, drawn with height = full widget's height, regardless of the value it represents. So for the most bars their lower end was far outside the box and therefore clipped off. So e.g. one couldn't see the lower round edges of rounded rectangles. This commit fixes that by appropriately varying the height that is passed into step_shape(), so that lower edges of the bars always exactly touch the lower edge of the graph. If the user wants to restore the prior behavior, they can simply ignore the passed-in height in step_shape() and just always draw their shape with height = full widget height. But they couldn't replicate the effect of this commit in their rc.lua without essentially writing their own graph widget. commit e25185b08da23745b5815f85f6e9e43222ed2294 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 08:42:54 2021 +0700 Avoid incremental transform shifting during graph bar rendering Instead of letting addition errors and cognitive load accumulate simply use the same offset calculation that is used for lines and reset the transform back to the top-left corner after every drawn bar. It's conceptually simpler, and will be useful later for stacked graphs and more. It also fixes a discrepancy between plain and step_shape rendering. Prior to this commit, bar coloring occurred with a disturbed transform, which was centered at the last drawn bar, wherever it happened to be. This meant that nontrivial colors, like gradients and images, were arbitrarily offset when step_shape was used. commit f3e98866d8583c35d0b557c09f529299edc9ba2c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 06:45:29 2021 +0700 Refactor out graph bar height expression into a variable commit f54528d6892f5aaa4595917853c9e2130f743fdb Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 06:20:25 2021 +0700 Draw graph bars with lines only when step_width == 1 Before this commit graph bars of step_width < 1 were drawn with lines of width 1, but that's a bit unfortunate, because it led to much overpainting, while still ending up with a graphically incorrect result. Let's draw such bars with rectangles and let cairo do things with subpixels, getting more graphically accurate result, while still keeping the common case of step_width == 1 (supposedly) fast-drawn with lines. commit b6515dca67c18b78eb5657378131a62ab43d4cfc Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:54:07 2021 +0700 Fix unsharp edges when drawing graph bars with rectangles The 0.5 offset is only helpful for 1-width strokes, not for fills. commit 7f3db8f07e82f821bcd1dc418d66564f537609d6 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:21:01 2021 +0700 Do coordinate transformations even if the value isn't drawn The graph presently doesn't draw values < 0, but there was a discrepancy between drawing with and without step_shape. The default line/rectangle drawing reserves an empty place where the skipped value should've been, but no such empty place is reserved, when step_shape is used. This commit fixes that. Skipped values always have their empty space now. commit 7b731ebfe96af7a9dba9c57371da6761cf22c00c Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 05:03:30 2021 +0700 Fix graph bar scaling when min_value is not 0 Previous calculation lead to underscaling of values so that even value = max_value wasn't drawn to full height. commit dca59fd8b7fff0e7e646f2dfc6bd92047028e5a8 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:18:40 2021 +0700 Calculate the horizontal graph bar offset only when needed commit 940ddf4b9825e9c3a91d276208c089d8c74e49db Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:17:23 2021 +0700 Call cr:move_to() only when drawing the graph with lines It's redundant otherwise and might even interfere with user's drawing in step_shape(). commit b5d5cd10ca29fb29cd751faaa95137c2fe89ff63 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 04:04:06 2021 +0700 Fix wrong horizontal offset calculations in widget.graph Indices in the loop are zero-based, so things like i-1 and i>1 aren't necessary and actually wouldn't have been correct even in a 1-based loop. step_shape = gears.shape.rectangle and step_shape = nil, which is supposed to default to rectangle according to docs, were drawn differently due to mismatched offset calculations, which led to problems especially noticeable when step_spacing is not zero, e.g: 1) whole graph shifted left too much, drawn partially off-screen. 2) whole graph shifted right too much, and the first bar placed closer to the rest than others. commit dc369fa198281e000afc1bd17326f3a264adf7d1 Author: Alex Belykh <albel727@ngs.ru> Date: Mon Apr 12 02:09:21 2021 +0700 Fix the "border_width affects graph bar width" bug Graph bars were drawn with lines of border_width thickness instead of 1, i.e. possibly too fat to be readable. commit 1ba73378cf29ed27a6ecd18716394779ceb543d9 Author: Alex Belykh <albel727@ngs.ru> Date: Wed Apr 14 00:13:03 2021 +0700 Simplify internal values representation in graph even more New values in graph._private.values were pushed to the end, and old values were removed from the beginning of the table. In draw() however newer values are drawn first, at the left edge of the graph, necessitating annoying idx = #values - idx conversions everywhere. In particular in stacked graph that means that values that are drawn together may have different indices. One has to shift the values array in add_value() either way, so one might as well insert new values at the beginning of the array and simplify the rest of the code. This doesn't seem like much yet, but it will prove to be much more convenient and less error-prone in what I'm going to do later. commit f70523ee68dbd6b67050ace4b82903a9b22440c7 Author: Alex Belykh <albel727@ngs.ru> Date: Tue Apr 13 13:35:10 2021 +0700 Simplify internal values representation in graph widget graph._private.values was either a table of values or a table of tables of values, depending on whether "stack" property is enabled, ... or a mix of both if user forgot to pass the second "group" parameter to graph:add_value(). This resulted in pretty fragile and confusing behavior, e.g. leaving user to wonder, why they see nothing more after setting stack=true for a graph in a previously working rc.lua, and demanding a very careful use of add_value() from the user, or else some values or even entire stacks would mysteriously vanish and errors in draw() get triggered, sometimes after a period of seemingly normal functioning. Now `values` is always a table of tables and the group parameter in add_value() defaults to 1, thus making the non-stacked graph a trivial variant of the stacked graph.
2021-05-20 17:14:03 +02:00
forced_height = 20, --DOC_HIDE
doc: Add examples for the graph.
2021-03-28 11:33:38 +02:00
widget = wibox.widget.graph,
}
for _, v in ipairs(data) do --DOC_HIDE
w1:add_value(v) --DOC_HIDE
w2:add_value(v) --DOC_HIDE
end --DOC_HIDE
parent:add(wibox.layout {--DOC_HIDE
{--DOC_HIDE
{--DOC_HIDE
markup = "<b>Without `min_value`</b>",--DOC_HIDE
widget = wibox.widget.textbox,--DOC_HIDE
},--DOC_HIDE
w1,--DOC_HIDE
layout = wibox.layout.fixed.vertical,--DOC_HIDE
},--DOC_HIDE
{--DOC_HIDE
{--DOC_HIDE
markup = "<b>With `min_value = 10`</b>",--DOC_HIDE
widget = wibox.widget.textbox,--DOC_HIDE
},--DOC_HIDE
w2,--DOC_HIDE
layout = wibox.layout.fixed.vertical,--DOC_HIDE
},--DOC_HIDE
forced_width = 240, --DOC_HIDE
spacing = 5, --DOC_HIDE
layout = wibox.layout.flex.horizontal --DOC_HIDE
}) --DOC_HIDE
--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80