From b304bf39e46f7bb330a26522c692c125905ca4c4 Mon Sep 17 00:00:00 2001 From: Andy Meneely Date: Tue, 17 Nov 2020 22:22:38 -0500 Subject: [PATCH] starting documenting xywh_shorthands --- CHANGELOG.md | 4 ++- docs/index.rst | 1 + docs/shorthands.rst | 29 +++++++++++++++++++++ docs/units.rst | 32 ++++++++++++++++++++++++ lib/squib/args/unit_conversion.rb | 2 +- lib/squib/args/xywh_shorthands.rb | 7 +++--- samples/units/_shorthands.rb | 12 +++++---- samples/units/shorthand_00_expected.png | Bin 1467 -> 1504 bytes 8 files changed, 77 insertions(+), 10 deletions(-) create mode 100644 docs/shorthands.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index a542907..979e17c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,9 @@ Squib follows [semantic versioning](http://semver.org). ## v0.16.0 / Unreleased Features: -* Autoscaling text! `ellipsize: :autoscale` will now downscale your `font_size` if the text ellipsized. Thanks @Qgel! (#288, #111). +* Special custom unit: cells. A "cell" defaults to 37.5px, or 1/8in, e.g. `x: '1 cell'` means `x: 37.5`. See the docs for details. +* Shorthands for `x`, `y`, `width`, and `height`! The words `x: 'middle'` and `x: 'middle + 1in'` will get interpreted. See the docs for details. +* Autoscaling text! `ellipsize: :autoscale` will now downscale your `font_size` if the text ellipsized. Thanks @Qgel! (#288, #111). * Option checking!! Completely reworked the way we handle arguments in Squib internally (no external behavioral differences). Now, when you give an option to Squib that is not expected. Since every DSL method "knows" what options it takes, that also means we have EVERY option properly documented (missed a few...) AND we have an automated test that will tell us if we forget to document it. Compatibility: diff --git a/docs/index.rst b/docs/index.rst index 51474d3..43747be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Contents: layouts data units + shorthands colors text_feature bleed diff --git a/docs/shorthands.rst b/docs/shorthands.rst new file mode 100644 index 0000000..7bea310 --- /dev/null +++ b/docs/shorthands.rst @@ -0,0 +1,29 @@ +XYWH Shorthands +=============== + +For the arguments ``x``, ``y``, ``width``, and ``height``, a few convenient shorthands are available. + +* ``middle`` for ``x`` and ``width`` refer to the deck's width / 2 +* ``middle`` for ``y`` and ``height`` refer to the deck's height / 2 +* ``deck`` refers to the deck's width for ``x`` and ``width`` +* ``deck`` refers to the deck's height for ``y`` and ``height`` +* You can offset from the middle by using +, -, and /, e.g. ``middle + 1in`` +* You can offset from the width or height using, e.g. ``width - 1in`` or ``height - 2mm`` +* Works with the ``cell`` unit as well, e.g. `middle + 1 cell`. See :doc:`units`. + +These are all passed as strings. So you will need to quote them in Ruby, or just plain in your layout YAML. + +Note that the following are NOT supported: + +* The `+=` operator when using `extends` in a layout file + +Samples +------- + +_shorthands.rb +^^^^^^^^^^^^^^ + +.. literalinclude:: ../samples/units/_shorthands.rb + :language: ruby + :linenos: + diff --git a/docs/units.rst b/docs/units.rst index d50f361..08faff2 100644 --- a/docs/units.rst +++ b/docs/units.rst @@ -3,6 +3,27 @@ Unit Conversion By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in "in", "cm", or "mm" and computing based on the current DPI. The dpi is set on `Squib::Deck.new` (not `config.yml`). +Cells +----- + +A "cell" is a custom unit in Squib that, by default, refers to ``37.5`` pixels. In a 300 DPI situation (i.e. the default), that refers to a 1/8 inch or 3.175mm. This tends to be a standard unit of measure in a lot of templates. By specifying your units in cells, you can increase your rapid prototyping without having to multiply 37.5. + +The ``cell_px`` measure is configurable. See :doc:`config`. + +To use the cell unit, you need to give Squib a string ending in `cell`, `cells`, or just `c`. For example: + +* ``2 cells`` +* ``1cell`` +* ``0.5c`` + +See more examples below. + +Samples +------- + +_units.rb +^^^^^^^^^ + Here are some examples, which `lives here `_ .. literalinclude:: ../samples/units/_units.rb @@ -12,3 +33,14 @@ Here are some examples, which `lives here + +_cells.rb +^^^^^^^^^ + +.. literalinclude:: ../samples/units/_cells.rb + :language: ruby + :linenos: + +.. raw:: html + + \ No newline at end of file diff --git a/lib/squib/args/unit_conversion.rb b/lib/squib/args/unit_conversion.rb index a6bee74..940e5b2 100644 --- a/lib/squib/args/unit_conversion.rb +++ b/lib/squib/args/unit_conversion.rb @@ -17,7 +17,7 @@ module Squib when /deg$/ # ends with "deg" arg.rstrip[0..-3].to_f * (Math::PI / 180.0) when /c(ell)?[s]?$/ # ends with 'c', 'cell', or 'cells' - arg.rstrip[0..-2].to_f * cell_px + arg.sub(/c(ell)?[s]?$/, '').to_f * cell_px else arg end diff --git a/lib/squib/args/xywh_shorthands.rb b/lib/squib/args/xywh_shorthands.rb index 2137ada..a349bb9 100644 --- a/lib/squib/args/xywh_shorthands.rb +++ b/lib/squib/args/xywh_shorthands.rb @@ -7,7 +7,6 @@ module Squib HEIGHT_MINUS_REGEX = /^height\s*\-\s*/ WIDTH_DIV_REGEX = /^width\s*\/\s*/ HEIGHT_DIV_REGEX = /^height\s*\/\s*/ - CELL_REGEX = /^c[ell]?[s]?\s*/ MIDDLE_PLUS_REGEX = /^middle\s*\+\s*/ MIDDLE_MINUS_REGEX = /^middle\s*\-\s*/ @@ -32,10 +31,12 @@ module Squib n = UnitConversion.parse(n) deck.height - n when WIDTH_DIV_REGEX # e.g. width / 3 - n = (arg_s.sub WIDTH_DIV_REGEX, '').to_f + n = arg_s.sub WIDTH_DIV_REGEX, '' + n = UnitConversion.parse(n).to_f deck.width / n when HEIGHT_DIV_REGEX # e.g. height / 3 - n = (arg_s.sub HEIGHT_DIV_REGEX, '').to_f + n = arg_s.sub HEIGHT_DIV_REGEX, '' + n = UnitConversion.parse(n).to_f deck.height / n when MIDDLE_PLUS_REGEX # e.g. middle + 1.5in n = arg_s.sub MIDDLE_PLUS_REGEX, '' diff --git a/samples/units/_shorthands.rb b/samples/units/_shorthands.rb index eb756e3..9d24e0f 100644 --- a/samples/units/_shorthands.rb +++ b/samples/units/_shorthands.rb @@ -25,10 +25,14 @@ Squib::Deck.new(width: '0.5in', height: '0.25in') do rect x: 10, y: 50, width: 10, height: 'height / 3', stroke_color: :purple + # And middle+/- + + rect x: 'middle + 0.1in', y: 'middle - 0.1in', + width: '0.1in', height: '0.1in', fill_color: :blue + # Layouts apply this too. use_layout file: 'shorthands.yml' rect layout: :example - # The x and y coordinates can also be "centered", assuming the # HOWEVER! Shorthands don't combine in an "extends" situation, # e.g. this won't work: @@ -38,10 +42,8 @@ Squib::Deck.new(width: '0.5in', height: '0.25in') do # extends: parent # x: += 0.5in - # These shorthands are not intended for every xywh parameter or length parameter - # e.g. this won't work - - + # These shorthands are not intended for every xywh parameter or + # length parameter, see docs for when they do or do not apply. save_png prefix: 'shorthand_' end diff --git a/samples/units/shorthand_00_expected.png b/samples/units/shorthand_00_expected.png index 7b21355e4d15b4f7b76421d2fa831cb194e283e7..d14cee5c41b1976f05066f8b85a9950226027f65 100644 GIT binary patch delta 1468 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