Skip to content

Commit bfb0a24

Browse files
98teg98teg
committed
Add the different files properties to doc
1 parent 4681998 commit bfb0a24

File tree

4 files changed

+362
-4
lines changed

4 files changed

+362
-4
lines changed

‎doc/files/JSON-PROPERTY-ARRAY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ Returned error:
155155
{
156156
"error": JSONProperty.Errors.ARRAY_BIGGER_THAN_MAX,
157157
"size": 4,
158-
"min": 3,
158+
"max": 3,
159159
"context": "furniture",
160160
"as_text": "The array size (4) is bigger than the maximum allowed (3), at 'furniture'."
161161
}

‎doc/files/JSON-PROPERTY-FILE.md‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,86 @@
11
# JSONPropertyFile
2+
3+
**extends [JSONProperty](./JSON-PROPERTY.md)**
4+
5+
**returns: [File](https://docs.godotengine.org/en/stable/classes/class_file.html?highlight=file)**
6+
7+
Only allows strings representing a path to a file. This path can be absolute or relative. When the file path is relative, it would be relative to the directory that contains the JSON configuration file that specifies this field. Please, use '/' as a [path delimiter](https://docs.godotengine.org/en/stable/getting_started/step_by_step/filesystem.html?highlight=file%20path#path-delimiter).
8+
9+
## Usage
10+
11+
Once you have instantiated the class, you can determine how to open the file via the 'set_mode_flag' method. It would be [File.READ](https://docs.godotengine.org/en/stable/classes/class_file.html?highlight=File.READ#enumerations) by default.
12+
13+
## Example
14+
15+
In this example, the configuration structure has one required property. The property 'file' must be a path to another file.
16+
17+
```GDScript
18+
# Create a JSON configuration file
19+
var json_config_file = JSONConfigFile.new()
20+
21+
# Add the 'file' property, which is a path to a file
22+
json_config_file.add_property("file", JSONPropertyFile.new())
23+
24+
# Validate input
25+
json_config_file.validate(json_file_path)
26+
```
27+
28+
### Valid JSON
29+
30+
This JSON has the required field.
31+
32+
```JSON
33+
{
34+
"file": "file.txt"
35+
}
36+
```
37+
38+
### Incorrect JSON: Wrong type
39+
40+
This JSON contains one error. The 'file' property is not the correct type.
41+
42+
```JSON
43+
{
44+
"file": 42
45+
}
46+
```
47+
48+
Returned error:
49+
50+
```GDScript
51+
[
52+
{
53+
"error": JSONProperty.Errors.WRONG_TYPE,
54+
"expected": JSONProperty.Types.FILE,
55+
"context": "file",
56+
"as_text": "Wrong type: expected 'file path', at 'file'."
57+
}
58+
]
59+
```
60+
61+
### Incorrect JSON: Missing image
62+
63+
This JSON contains one error. The 'file' property indicates a path to a file that does not exist.
64+
65+
```JSON
66+
{
67+
"file": "missing_file.txt"
68+
}
69+
```
70+
71+
Returned error:
72+
73+
```GDScript
74+
[
75+
{
76+
"error": JSONProperty.Errors.COULD_NOT_OPEN_IMAGE,
77+
"code": ERR_FILE_NOT_FOUND,
78+
"context": "file",
79+
"as_text": "Could not open the file, at 'file'."
80+
}
81+
]
82+
```
83+
284
## Functions
385

486
The public methods of this class are:
@@ -7,4 +89,13 @@ The public methods of this class are:
789
|-|-|-|-|
890
| **set_preprocessor** | **processor -> JSONConfigProcessor:** <br> Object that defines the function to execute before the validation process. | Sets the process to execute before the validation process. | Nothing. |
991
| **set_postprocessor** | **processor -> JSONConfigProcessor:** <br> Object that defines the function to execute after the validation process. | Sets the process to execute after the validation process. | Nothing. |
10-
| **set_mode_flag** | **mode_flag -> int:** <br> The flag that determines how to open the file. <br><br> **NOTE:** Check [File.ModeFlags](https://docs.godotengine.org/en/stable/classes/class_file.html?highlight=File#enum-file-modeflags) for more information. | Determines how to open the file. | Nothing.
92+
| **set_mode_flag** | **mode_flag -> int:** <br> The flag that determines how to open the file. <br><br> **NOTE:** Check [File.ModeFlags](https://docs.godotengine.org/en/stable/classes/class_file.html?highlight=File#enum-file-modeflags) for more information. | Determines how to open the file. | Nothing.
93+
94+
## Errors
95+
96+
This class could directly raise any of the following errors:
97+
98+
| Enum value | Description | Params | As text |
99+
|-|-|-|-|
100+
| WRONG_TYPE | The type of the input does not match the expected one. | **expected -> int:** <br> Takes the value [FILE](./ENUMS.md). | Wrong type: expected 'file path' |
101+
| COULD_NOT_OPEN_FILE | The file path leads to a nonexistent file or an error occurred when opening the file. | **code -> int:** <br> Error code returned by [File.open()](https://docs.godotengine.org/en/stable/classes/class_file.html?highlight=File#class-file-method-open). | Could not open the file |

‎doc/files/JSON-PROPERTY-IMAGE.md‎

Lines changed: 129 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,114 @@
11
# JSONPropertyImage
2+
3+
**extends [JSONProperty](./JSON-PROPERTY.md)**
4+
5+
**returns: [Image](https://docs.godotengine.org/en/stable/classes/class_image.html?highlight=image)**
6+
7+
Only allows strings representing a path to an image. This path can be absolute or relative. When the file path is relative, it would be relative to the directory that contains the JSON configuration file that specifies this field. Please, use '/' as a [path delimiter](https://docs.godotengine.org/en/stable/getting_started/step_by_step/filesystem.html?highlight=file%20path#path-delimiter). Also, check Godot's [supported image formats](https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html#supported-image-formats).
8+
9+
## Usage
10+
11+
Once you have instantiated the class, you can determine the size of the image via the 'set_size' method. By default, the images would be resizable and rescaled using [Image.INTERPOLATE_BILINEAR](https://docs.godotengine.org/en/stable/classes/class_image.html?highlight=Image#enum-image-interpolation). That means that when the image size is different, this property will raise a warning. If you want it to raise an error, set the third parameter in 'set_size' to 'false'.
12+
13+
## Example
14+
15+
In this example, the configuration structure has one required property. The property 'image' must be a path to an image which size should be 64x64.
16+
17+
```GDScript
18+
# Create a JSON configuration file
19+
var json_config_file = JSONConfigFile.new()
20+
21+
# Create an image property
22+
var image_property = JSONPropertyImage.new()
23+
image_property.set_size(64, 64)
24+
25+
# Add the 'image' property, which is a path to an image
26+
json_config_file.add_property("image", image_property)
27+
28+
# Validate input
29+
json_config_file.validate(json_file_path)
30+
```
31+
32+
### Valid JSON
33+
34+
This JSON has the required field.
35+
36+
```JSON
37+
{
38+
"image": "image.png"
39+
}
40+
```
41+
42+
### Incorrect JSON: Wrong type
43+
44+
This JSON contains one error. The 'image' property is not the correct type.
45+
46+
```JSON
47+
{
48+
"image": 42
49+
}
50+
```
51+
52+
Returned error:
53+
54+
```GDScript
55+
[
56+
{
57+
"error": JSONProperty.Errors.WRONG_TYPE,
58+
"expected": JSONProperty.Types.IMAGE,
59+
"context": "image",
60+
"as_text": "Wrong type: expected 'image path', at 'image'."
61+
}
62+
]
63+
```
64+
65+
### Incorrect JSON: Missing image
66+
67+
This JSON contains one error. The 'image' property indicates a path to an image that does not exist.
68+
69+
```JSON
70+
{
71+
"image": "missing_image.png"
72+
}
73+
```
74+
75+
Returned error:
76+
77+
```GDScript
78+
[
79+
{
80+
"error": JSONProperty.Errors.COULD_NOT_OPEN_IMAGE,
81+
"code": ERR_FILE_NOT_FOUND,
82+
"context": "image",
83+
"as_text": "Could not open the image, at 'image'."
84+
}
85+
]
86+
```
87+
88+
### Semi-incorrect JSON: Wrong size image
89+
90+
This JSON contains one warning. The 'image' property indicates a path to an image which size is not the desired one.
91+
92+
```JSON
93+
{
94+
"image": "32x32_image.png"
95+
}
96+
```
97+
98+
Returned warning:
99+
100+
```GDScript
101+
[
102+
{
103+
"warning": Warnings.IMAGE_WRONG_SIZE,
104+
"expected_size": [64, 64],
105+
"size": [32, 32],
106+
"context": "image",
107+
"as_text": "The image is not the correct size (64, 64), at 'image'."
108+
}
109+
]
110+
```
111+
2112
## Functions
3113

4114
The public methods of this class are:
@@ -7,4 +117,22 @@ The public methods of this class are:
7117
|-|-|-|-|
8118
| **set_preprocessor** | **processor -> JSONConfigProcessor:** <br> Object that defines the function to execute before the validation process. | Sets the process to execute before the validation process. | Nothing. |
9119
| **set_postprocessor** | **processor -> JSONConfigProcessor:** <br> Object that defines the function to execute after the validation process. | Sets the process to execute after the validation process. | Nothing. |
10-
| **set_size** | **width -> int:** <br> Width of the image. <br> **height -> int:** <br> Height of the image. <br> **resizable -> bool(true):** <br> Determines if the image is resizable. If it is, it will raise a warning whenever the size of the input image is different than this size, and then it will resize the image. If it is not, it will raise an error instead. <br> **interpolation -> int(Image.INTERPOLATE_BILINEAR):** <br> Interpolation tecnich to apply whenever the size of the input image is different and it must be resized. <br><br> **NOTE:** Check [Image.Interpolation](https://docs.godotengine.org/en/stable/classes/class_image.html?highlight=Image#enum-image-interpolation) for more information. | Sets the recommended, or required, size of the image. | Nothing. |
120+
| **set_size** | **width -> int:** <br> Width of the image. <br> **height -> int:** <br> Height of the image. <br> **resizable -> bool(true):** <br> Determines if the image is resizable. If it is, it will raise a warning whenever the size of the input image is different than this size, and then it will resize the image. If it is not, it will raise an error instead. <br> **interpolation -> int(Image.INTERPOLATE_BILINEAR):** <br> The interpolation technic to apply whenever the size of the input image is different, and it must be resized. <br><br> **NOTE:** Check [Image.Interpolation](https://docs.godotengine.org/en/stable/classes/class_image.html?highlight=Image#enum-image-interpolation) for more information. | Sets the recommended, or required, size of the image. | Nothing. |
121+
122+
## Errors
123+
124+
This class could directly raise any of the following errors:
125+
126+
| Enum value | Description | Params | As text |
127+
|-|-|-|-|
128+
| WRONG_TYPE | The type of the input does not match the expected one. | **expected -> int:** <br> Takes the value [IMAGE](./ENUMS.md). | Wrong type: expected 'file path' |
129+
| COULD_NOT_OPEN_IMAGE | The image path leads to a nonexistent image or an error occurred when loading the image. | **code -> int:** <br> Error code returned by [Image.load()](https://docs.godotengine.org/en/stable/classes/class_image.html?highlight=Image#class-image-method-load). | Could not open the image |
130+
IMAGE_WRONG_SIZE | The image has not the correct size. | **expected_size -> array:** <br> Array with two integers representing the expected size of the image. <br> **size -> array:** <br> Array with two integers representing the actual size of the image. | The image is not the correct size ({expected_size})
131+
132+
## Warnings
133+
134+
This class could directly raise any of the following warnings:
135+
136+
| Enum value | Description | Params | As text |
137+
|-|-|-|-|
138+
IMAGE_WRONG_SIZE | The image has not the correct size. | **expected_size -> array:** <br> Array with two integers representing the expected size of the image. <br> **size -> array:** <br> Array with two integers representing the actual size of the image. | The image is not the correct size ({expected_size})

0 commit comments

Comments
 (0)