ACTIONS_README.md · 科帕奇/LibreCAD

This pull request includes several handy actions for entities editing and modification (see below).

Actions are:
1) Draw Cross (https://youtu.be/H9Lul0J02a0)
2) Draw Star (https://youtu.be/bAD7kkAR5wA)
3) Draw Rectangle - 1 Point (https://youtu.be/eOscpTiWJMY)
4) Draw Rectangle - 2 Points (https://youtu.be/9bjBZAcEmVc)
4) Draw Rectangle - 3 Points (https://youtu.be/IJhG3Rz9U5o)
5) Draw Line of Points (https://youtu.be/8kDSSKg-vqU)
6) Draw Snake Line (https://youtu.be/bXom0IWw4R4)
7) Draw Snake (X) Line (https://youtu.be/bXom0IWw4R4)
8) Draw Snake (X) Line (https://youtu.be/bXom0IWw4R4)
9) Draw Angle From Line (https://youtu.be/ZcnIUXZdSBI)
10) Draw Orthogonal From Line (https://youtu.be/sfO2aUeQ_2E)
11) Draw Line from Point To Line (https://youtu.be/3bEWIryP6jQ)
12) Slice/Divide Line (https://youtu.be/z0I8N73aWFM)
13) Slice/Divide Circle/Arc (https://youtu.be/ILACvThv6I4)
14) Draw Circle by Arc (https://youtu.be/xSJnC-Mvczw)
15) Duplicate entity (https://youtu.be/xSJnC-Mvczw)
16) Lines Join (https://youtu.be/NCqodd0i_gE)
    17) Break/Divide (line, arc, circle) https://youtu.be/_UHawUJXZe0
18) Line Gap (https://youtu.be/0Y0YsNSZIJA)

### Action Details

The following actions are included:

### Cross Action

This action draws cross for selected circle, arc, ellipse or ellipse arc. Intersection of cross lines is located in the center point of entity.

Cross is drawn using active pen and layer.

#### Example Video: https://youtu.be/H9Lul0J02a0

**Options:**

1) **X** - horizontal size value

2) **Y** - vertical size value

3) **Angle** - angle used to rotate the cross (between x-axis and horizontal line)

4) **Type** - defines type of cross size calculation. There are the following size types:
    - **Extension**  - cross extends selected entity on specified x and y values (so the lengths of lines is radius + specified x or y)
    - **Total Length** - x and y values are considered as absolute length value
    - **Percentage** - x and y values are considered as percentage of entity's radius
 
#### Existing Pre-Selection:

If there are selected entities during action's invocation, cross for each applicable entity type is created based previously on saved settings.

#### Command widget
Action is not fully scriptable, as requires mouse selection of entity.

#### Invocation Commands:

```cross``` or ```cx```

##### Action Commands:

No additional commands

#### Mouse + SHIFT mode:
No support

---
### Star Action
This action draws a star with given amount of rays. It is possible to create symmetric or non-symmetric star, and specify rounding radiuses for outer and inner vertexes.

Star is drawn using active pen and layer.

#### Example Video: https://youtu.be/bAD7kkAR5wA

#### Options:

1) **Symmetric** - flag that indicates whether star is symmetric

2) **Number** - number of rays (min is 3)

3) **Radius Outer** - Rounding radius for outer vertexes of rays (if any)

3) **Radius Inner**
Rounding radius for inner vertexes of rays (if any)

4) **Polyline** Flag indicates whether all elements of start should be drawn as individual entities or as single polyline.

#### Existing Selection:

No support

#### Command widget

Action is fully scriptable and operations may be performed via command widget only.

##### Invocation Command:

```star``` or ```st```

##### Action Commands:

Positions for center of star, outer ray vertex and inner ray vertex may be entered as coordinates.
Also, the following commands are supported:

```number``` - specified amount of rays

```radius``` - allows to specify rounding radiuses

```sym``` - specified that star is symmetric

```nosym``` - specifies that start is not symmetric

```nopoly``` - do not create polyline

```usepoly``` - draw star as single polyline

#### Mouse + SHIFT mode: 
For setting center point of star state of the action, allows snapping center to relative zero point.

----
###  Draw Rectangle (1 Point) Action
This action draws a rectangle of specified size and places it into specified insertion point.

Rectangle is drawn using active pen and layer.

#### Example Video: https://youtu.be/eOscpTiWJMY

#### Options:

1) **Width** - width of rectangle

2) **Height** - height of rectangle

3) **Snap** - defines which part of rectangle will be used as as snap point (and so it will be placed into insertion point)  
there are the following options for snap: 
    * **Top Left** - top left corner of rect
    * **Top** - middle of top edge 
    * **Top-Right** - top-right corner
    * **Left** - middle point of left edge
    * **Middle** - central point of rectangle
    * **Right** - middle point of right edge
    * **Bottom-left** - bottom-left corner
    * **Bottom** - middle of bottom edge
    * **Bottom-Right** - bottom-right corner
4) **Base Angle** - rotation angle of rectangle (betwen x-axis and bottom edge)
5) **Polyline** - Flag indicates whether all elements of rectangle should be drawn as individual entities or as single polyline.
6) **Corners** - Defines now corners of rectangle should be drawn. The following options are available:
   * **Straight** - normal 90 degrees corners
   * **Round** - rounded (arc) corners with specified radius
   * **Bevel** - bevels with specified size 
7) **Edges**  - for _Straight_ corner mode, allows to specify which edges of rectangle should be shown. If not all edges are set, it is possible to draw 2 parallel lines. Options are:
   * **Both** - all edges are draws, so result is rect
   * **Vertical** - only vertical edges are drawn, 2 parallel lines
   * **Horizontal** - only horizontal edges are drawn, 2 parallel lines
9) **Radius** - for _Round_ corners mode, radius of rounding corners arcs
10) **Snap Shift** - for _Round_ corners mode, flag indicates that normal snap point should be adjusted and be located, say, not at the corner of rect, but in the center point of rounding arc
11) **Size inner** - for _Round_ corners mode, if set this flag indicates that size of rectangle should be applied not to outer size of rectangle, but for size between centers of rounding arcs.
12) **Length X** - for _Bevel_ corners mode, specifies bevel size by x-axis
13) **Length Y** - for _Bevel_ corners mode, specifies bevel size by y-axis

#### Existing Selection:

No support

#### Command widget

Action is fully scriptable and operations may be performed via command widget only.

##### Invocation Command:

```rect1``` or ```re1```

##### Action Commands:

Position for insertion point may be entered as coordinates.

Also, the following commands are supported:

```width``` - initiates entering width

```height``` - initiates entering height

```size``` - initiates entering size of rect (as width, height pair, similar to coordinates)

```pos``` -  switches to entering insertion point coordinates

```snap1``` - initiates entering snap mode for insertion point. Commands for snap point type are:
```topl, top, topr, left, middle, right, bottoml, bottom, bottomr```

```snapcorner``` - switches to snap to corner mode (opposite to ```snapshift```)

```snapshift``` - switches to snap to center of rounded corner arc mode (opposite to ```snapshift```)

```sizeout``` -  switches sizes calculation relating to corners (opposite to ```sizein```)

```sizein``` -   switches sizes calculation relating to centers of rounding arcs (opposite to ```sizeout```)

```angle``` -   initiates entering of base angle of rect (angle from corner1 to corner2)

```radius``` - initiates entering rounding radius for corners

```bevels``` - initiates entering of bevels or setting bevels corners mode

```corners``` - initiates entering corners mode. Command values for corners are: ```str, round, bevels```

```edges``` - initiates entering corners mode. Command values for corners are: ```both, hor, vert```

```usepoly``` - draw rectangle as single polyline

```usepoly``` - disables drawing rect as polyline (so all elements are individual entities)

#### Mouse + SHIFT mode
If relative zero point is valid, uses it as rectangle insertion point.

----
###  Draw Rectangle (2 Points) Action
This action draws a rectangle by specifying positions of two snap points (specified by settings) of rectangle.
Such customizable snapping mode allows better positioning of created rectangle.

Rectangle is drawn using active pen and layer.

#### Example Video: https://youtu.be/9bjBZAcEmVc

#### Options:

1) **Start Snap** - defines which part of rectangle will be used as a first snap point (and so it will be placed into insertion point)  
   there are the following options for snap:
    * **Corner** - corner of rectangle
    * **Mid-Vertical** - middle of vertical edge
    * **Mid-Horizontal** - middle point of horizontal edge    
    * **Middle** - central point of rectangle
2) **End Snap** - defines which part of rectangle will be used as a first snap point (and so it will be placed into insertion point)  
   there are the following options for snap:
    * **Corner** - corner of rectangle
    * **Mid-Vertical** - middle of vertical edge
    * **Mid-Horizontal** - middle point of horizontal edge
    * **Middle** - central point of rectangle 
4) **Base Angle** - rotation angle of rectangle (between x-axis and bottom edge)
5) **Polyline** - Flag indicates whether all elements of rectangle should be drawn as individual entities or as single polyline.
6) **Corners** - Defines now corners of rectangle should be drawn. The following options are available:
    * **Straight** - normal 90 degrees corners
    * **Round** - rounded (arc) corners with specified radius
    * **Bevel** - bevels with specified size
7) **Edges**  - for _Straight_ corner mode, allows to specify which edges of rectangle should be shown. If not all edges are set, it is possible to draw 2 parallel lines. Options are:
    * **Both** - all edges are draws, so result is rect
    * **Vertical** - only vertical edges are drawn, 2 parallel lines
    * **Horizontal** - only horizontal edges are drawn, 2 parallel lines
9) **Radius** - for _Round_ corners mode, radius of rounding corners arcs
10) **Snap Shift** - for _Round_ corners mode, flag indicates that normal snap point should be adjusted and be located, say, not at the corner of rect, but in the center point of rounding arc
12) **Length X** - for _Bevel_ corners mode, specifies bevel size by x-axis
13) **Length Y** - for _Bevel_ corners mode, specifies bevel size by y-axis

#### Existing Selection:

No support

#### Command widget

Action is fully scriptable and operations may be performed via command widget only.

##### Invocation Command:

```rect2``` or ```re2```

##### Action Commands:

Position for start snap point and end snap point may be entered as coordinates.

Also, the following commands are supported:

```snap1``` - starts entering of snap mode for point 1. Options for snap point type are:
```corner, mid-vert, mid-hor, middle```

```snap2``` - starts entering of snap mode for point 1. Options for snap point type are:
```corner, mid-vert, mid-hor, middle```