...docs

plandem · Jul 18, 2019 · 4538b54 · 4538b54
1 parent 18c66f2
commit 4538b54
Show file tree

Hide file tree

Showing 6 changed files with 199 additions and 70 deletions.
diff --git a/cell.go b/cell.go
@@ -115,8 +115,8 @@ func (c *Cell) Bool() (bool, error) {
  return false, errTypeMismatch
 }
 
-//SetGeneral sets the value as general type
-func (c *Cell) SetGeneral(value string) {
+//setGeneral sets the value as general type
+func (c *Cell) setGeneral(value string) {
  c.ml.Type = types.CellTypeGeneral
  c.ml.Value = value
  c.ml.Formula = nil
@@ -290,7 +290,7 @@ func (c *Cell) SetValue(value interface{}) {
  case nil:
  c.Reset()
  default:
- c.SetGeneral(fmt.Sprintf("%v", value))
+ c.setGeneral(fmt.Sprintf("%v", value))
  }
 }
 

diff --git a/docs/src/guide/number_format.md b/docs/src/guide/number_format.md
@@ -0,0 +1,142 @@
+# Number Format Codes
+[[toc]]
+Number format code is way to show numeric value. It controls whether a number is displayed as an integer, a floating number, a date, a currency value or some other user defined format.
+
+::: tip
+Xlsx2Go supports built-in Excel codes and will try to detect/convert to proper internal ID, as well as custom codes - use it as is without worrying.
+:::
+
+### Built-in Codes
+::: note General type
+* `@`
+* `General`
+:::
+
+::: note Integer number 
+* `0`
+* `0%`
+* `(#,##0_);(#,##0)`
+* `(#,##0_);[RED](#,##0)`
+::: 
+
+::: note Float number
+* `0.00`
+* `#,##0`
+* `#,##0.00`
+* `($#,##0_);($#,##0)`
+* `($#,##0_);[RED]($#,##0)`
+* `($#,##0.00_);($#,##0.00_)`
+* `($#,##0.00_);[RED]($#,##0.00_)`
+* `0.00%`
+* `0.00E+00`
+* `# ?/?`
+* `# ??/??`
+* `(#,##0.00);(#,##0.00)`
+* `(#,##0.00);[RED](#,##0.00)`
+* `_(*#,##0_);_(*(#,##0);_(*"-"_);_(@_)`
+* `_($*#,##0_);_($*(#,##0);_(*"-"_);_(@_)`
+* `_(*#,##0.00_);_(*(#,##0.00);_(*"-"??_);_(@_)`
+* `_($*#,##0.00_);_($*(#,##0.00);_(*"-"??_);_(@_)`
+* `##0.0E+0`
+:::
+
+::: note Date
+* `m-d-yy`
+* `d-mmm-yy`
+* `d-mmm`
+* `mmm-yy` 
+::: 
+
+::: note Time
+* `h:mm AM/PM`
+* `h:mm:ss AM/PM`
+* `h:mm`
+* `h:mm:ss` 
+::: 
+
+::: note Date+Time
+* `m-d-yy h:mm`
+:::
+
+::: note DeltaTime
+* `mm:ss`
+* `[h]:mm:ss`
+* `mm:ss.0`
+:::
+
+### Custom Codes
+Format code can control any aspect of number formatting allowed by Excel:
+
+::: tip Currency
+The `$` in format appears as the local currency symbol.
+:::
+
+::: tip Colors
+The color format should have one of the following values: 
+
+`[Black]` `[Blue]` `[Cyan]` `[Green]` `[Magenta]` `[Red]` `[White]` `[Yellow]`
+:::
+
+#### Examples
+<table>
+<tr>
+ <th style="text-align: right;">Number code</th>
+ <th style="text-align: right;">Go Value</th>
+ <th style="text-align: right;">Excel Output</th>
+</th>
+<tr>
+ <td style="text-align: right;"><code>dd/mm/yyyy hh:mm AM/PM</code></td>
+ <td style="text-align: right;">time.Now()</td>
+ <td style="text-align: right;">18/07/2019 12:30 AM</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>mm/dd/yy</code></td>
+ <td style="text-align: right;">time.Now()</td>
+ <td style="text-align: right;">07/18/19</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>mmm d yyyy</code></td>
+ <td style="text-align: right;">time.Now()</td>
+ <td style="text-align: right;">Jul 18 2019</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>d mmmm yyyy</code></td>
+ <td style="text-align: right;">time.Now()</td>
+ <td style="text-align: right;">18 July 2019</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>0.000</code></td>
+ <td style="text-align: right;">1.2345678</td>
+ <td style="text-align: right;">1.235</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>#,##0</code></td>
+ <td style="text-align: right;">1234.567</td>
+ <td style="text-align: right;">1,235</td>
+</tr>
+<tr>
+ <td style="text-align: right;"><code>0 "dollar and" .00 "cents"</code></td>
+ <td style="text-align: right;">1.87</td>
+ <td style="text-align: right;">1 dollar and .87 cents</td>
+</tr>
+<tr>
+ <td style="text-align: right;" rowspan="3"><code>[Green]General;[Red]-General;General</code></td>
+ <td style="text-align: right;">12345</td>
+ <td style="text-align: right;"><span style="color:green">1235</span></td>
+</tr>
+<tr>
+ <td style="text-align: right;">-12345</td>
+ <td style="text-align: right;"><span style="color:red">-12345</span></td>
+</tr>
+<tr>
+ <td style="text-align: right;">0</td>
+ <td style="text-align: right;">0</td>
+</tr>
+</table>
+
+::: note
+
+::: right
+For more information about custom formats, check [Microsoft Documentation](https://support.office.com/en-us/article/create-a-custom-number-format-78f2a361-936b-4c03-8772-09fab54be7f4?ui=en-US&rs=en-US&ad=US)
+:::
+
diff --git a/docs/src/guide/styles-formatting.md b/docs/src/guide/styles-formatting.md
@@ -1,14 +1,59 @@
 # Styles Formatting
 [[toc]]
 
+Styles can be defined through special type - general type for all available styles. But information that will be using to style object, depends on usage, e.g. to style cells everything will be use, to style rich texts - only font information. 
+
+```go
+ // create a new styles
+ ss := styles.New(
+ styles.Font.Bold,
+ styles.Font.Color("#ff0000"),
+ )
+
+ //update styles
+ ss.Set(
+ styles.Border.Color("#009000"),
+ styles.Border.Type(styles.BorderStyleMedium),
+ )
+```
+::: warning Modify Styles
+While you can modify created styles, you should keep in mind, that modifying will work only before applying styles to cell and any modifications after applying, will create new styles.
+:::
+
+```go
+ ss := styles.New(
+ styles.Font.Bold,
+ ))
+
+ //font will be `bold`
+ sheet.CellByRef("A1").SetStyles(ss)
+
+ //modify styles
+ ss.Set(
+ styles.Font.Color("#ff0000"),
+ )
+
+ //`A2` - will be `bold and red` 
+ //`A1` - will be only `bold` and without color
+ sheet.CellByRef("A2").SetStyles(ss)
+```
+
 ### Font
+::: warning
+Excel can only display installed fonts, that's why using standard fonts(e.g.: `Calibri`, `Times New Roman` or `Courier New`) is highly recommended.
+:::
+
+::: note
+The default font for cell is `Calibri` (Excel 2007+)
+:::
+<<< @/src/code/merged_cells_test.go
 
 ### Fill
 
 ### Border
 
 ### Alignment
 
-### Format
+### Number Format
 
 ### Protection
diff --git a/docs/src/guide/values.md b/docs/src/guide/values.md
@@ -94,69 +94,14 @@ Keep in mind, that text can be a simple string, as well as full featured rich te
 Check [Rich Text](/guide/rich-text.md) for more information about rich texts.
 :::
 
-### Custom Formats
+### Number Formats
 In some cases we want to set value, but also use format how to display that value.
 
 ```go
  //set floating number value and related format code
  sheet.CellByRef("A1").SetValueWithFormat(12345.12345, "0.00")
 ```
 
-#### Format Codes
-::: tip
-Xlsx2Go supports default Excel codes and will try to detect/convert to proper internal code, as well as custom codes - use it as is without worrying.
-:::
-
-::: note General type
-* `@`
-:::
-
-::: note Integer number type 
-* `0`
-* `0%`
-* `(#,##0_);(#,##0)`
-* `(#,##0_);[RED](#,##0)`
-::: 
-
-::: note Float number type
-* `0.00`
-* `#,##0`
-* `#,##0.00`
-* `($#,##0_);($#,##0)`
-* `($#,##0_);[RED]($#,##0)`
-* `($#,##0.00_);($#,##0.00_)`
-* `($#,##0.00_);[RED]($#,##0.00_)`
-* `0.00%`
-* `0.00E+00`
-* `# ?/?`
-* `# ??/??`
-* `(#,##0.00);(#,##0.00)`
-* `(#,##0.00);[RED](#,##0.00)`
-* `_(*#,##0_);_(*(#,##0);_(*"-"_);_(@_)`
-* `_($*#,##0_);_($*(#,##0);_(*"-"_);_(@_)`
-* `_(*#,##0.00_);_(*(#,##0.00);_(*"-"??_);_(@_)`
-* `_($*#,##0.00_);_($*(#,##0.00);_(*"-"??_);_(@_)`
-* `##0.0E+0`
-:::
-
-::: note Date type
-* `m-d-yy`
-* `d-mmm-yy`
-* `d-mmm`
-* `mmm-yy` 
-::: 
-
-::: note Time type
-* `h:mm AM/PM`
-* `h:mm:ss AM/PM`
-* `h:mm`
-* `h:mm:ss` 
-::: 
-
-::: note DeltaTime type
-* `m-d-yy h:mm`
-* `mm:ss`
-* `[h]:mm:ss`
-* `mm:ss.0`
-:::
-
+::: tip Format Codes
+Check [Number Format](/guide/number_format.md) for more information about codes for number format.
+:::
diff --git a/internal/number_format/indexed.go b/internal/number_format/indexed.go
@@ -25,7 +25,7 @@ func init() {
  }
 
  builtIn = map[int]*builtInFormat{
- 0x00: {ml.NumberFormat{ID: 0x00, Code: `@`}, General},
+ 0x00: {ml.NumberFormat{ID: 0x00, Code: `General`}, General},
  0x01: {ml.NumberFormat{ID: 0x01, Code: `0`}, Integer},
  0x02: {ml.NumberFormat{ID: 0x02, Code: `0.00`}, Float},
  0x03: {ml.NumberFormat{ID: 0x03, Code: `#,##0`}, Float},

diff --git a/internal/number_format/types_test.go b/internal/number_format/types_test.go
@@ -20,7 +20,7 @@ func TestNumberFormat(t *testing.T) {
  require.Equal(t, builtIn[0x00], Resolve(ml.NumberFormat{ID: 0, Code: "0.00"}))
 
  //built-in ID was provided, ignore custom CODE and return general code/type
- unknownBuiltIn := &builtInFormat{ml.NumberFormat{ID: 162, Code: "@"}, General}
+ unknownBuiltIn := &builtInFormat{ml.NumberFormat{ID: 162, Code: "General"}, General}
  require.Equal(t, unknownBuiltIn, Resolve(ml.NumberFormat(ml.NumberFormat{ID: 162, Code: "abcd"})))
 
  //built-in CODE was provided, ignore custom ID
@@ -30,13 +30,10 @@ func TestNumberFormat(t *testing.T) {
  require.Nil(t, Resolve(ml.NumberFormat{ID: 1000, Code: "abcde"}))
 
  //built-in ID was provided, ignore custom CODE
- require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 0, Code: "@"}), New(0, "abcd"))
-
- //built-in ID was provided, ignore custom CODE
- require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 0, Code: "@"}), New(0, "abcd"))
+ require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 0, Code: "General"}), New(0, "abcd"))
 
  //built-in ID was provided, ignore built-in CODE
- require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 0, Code: "@"}), New(0, "0.00"))
+ require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 0, Code: "General"}), New(0, "0.00"))
 
  //built-in CODE was provided, ignore custom ID
  require.Equal(t, ml.NumberFormat(ml.NumberFormat{ID: 2, Code: "0.00"}), New(1000, "0.00"))