[Feature request]: add documentation / wiki

[sebastiaanfranken]

Describe the feature you'd like
Adding documentation of the internal JSON structure (you can get/edit with the "export layouts" button) so you can edit your wanted layouts. This is so you can import/export your own custom layout(s) easily.

Additional context
None that I can think of.

[domferr]

Hey, thank you this is a nice idea

[sebastiaanfranken]

I have/had some issues with the current JSON, for example what the "groups" key is for exactly. Also the X and Y, those are logical, only question is do they start bottom left or top left of the screen?

[domferr]

The JSON file contains a list of Layout objects. A Layout is an object with two properties: an identifier (string) and a list of Tile objects. A Tile object has 5 properties: x (floating point number), y (floating point number), width (floating point number), height (floating point number) and a list of identifiers called groups.
The coordinates x and y and the sizes width and height are percentages relative to the screen size. Both x and y refer to the top left position of the Tile. For example, a Tile with x = 0.22 and y = 0.5, on a screen with resolution 1080x1920 is placed at position x = 0.22 * 1920 and y = 0.5 * 1080. Tile's width and height follow the same approach. This allows Tiling Shell to work with layouts and tiles for any screens, proportions and even scaling factors!

Tile's group attribute is a list of indexes. The goal here is to group nearby tiles, according to how they are created in the editor. A simple way to visualize them is to look at the sliders in the layout editor.

For example, the following JSON represents the layout in the image below:

{
   "id":"Layout 1",
   "tiles":[
      { // this is the TOP-LEFT
         "x":0,
         "y":0,
         "width":0.22,
         "height":0.5,
         "groups":[
            1,
            2
         ]
      },
      { // this is the BOTTOM-LEFT
         "x":0,
         "y":0.5,
         "width":0.22,
         "height":0.5,
         "groups":[
            1,
            2
         ]
      },
      { // this is the CENTER
         "x":0.22,
         "y":0,
         "width":0.56,
         "height":1,
         "groups":[
            2,
            3
         ]
      },
      { // this is the TOP-RIGHT
         "x":0.78,
         "y":0,
         "width":0.22,
         "height":0.5,
         "groups":[
            3,
            4
         ]
      },
      { // this is the BOTTOM-RIGHT
         "x":0.78,
         "y":0.5,
         "width":0.22,
         "height":0.5,
         "groups":[
            3,
            4
         ]
      }
   ]
}

Top-left tile is in a group with the bottom-left tile (group number 1), top-left and bottom-left tiles are in a group with the tile in the center (group number 2), top-right and bottom-right tiles are in a group with the tile in the center (group number 3), top-right tile is in a group with the bottom-right tile (group number 4). The sliders in the image below visualize the groups:

[sebastiaanfranken]

Ah,so my suspicions were wrong! Thanks for pointing out that X and Y are relative, not absolute. I thought they were absolute. I was playing around with a monocle layout, and that worked so I thought I'd flip it around (the major pane on the right, not the left), but couldn't get that to work from pure code. Let's see if with your info I can get it down, if that's the case I can (if you want) help out with writing documentation

[domferr]

You're welcome! Yes, your help with writing documentation about this would be awesome, thank you! Feel free to reply here for any doubt! Hope you'll create the layout you want, but if you need any help just ping me and I'll be more than happy to give you a hand!

[sebastiaanfranken]

So I created two layouts, a 50/50 split and a 33/33/33 split, with the following code:

[
	{
		"id": "split-half",
		"tiles": [
			{
				"x": 0,
				"y": 0,
				"width": 0.5,
				"height": 1,
				"groups": [
					2
				]
			},
			{
				"x": 0.5,
				"y": 0,
				"width": 0.5,
				"height": 1,
				"groups": [
					1
				]
			}
		]
	},
	{
		"id": "split-thirds",
		"tiles": [
			{
				"x": 0,
				"y": 0,
				"width": 0.333,
				"height": 1,
				"groups": [
					2,
					3
				]
			},
			{
				"x": 0.333,
				"y": 0,
				"width": 0.333,
				"height": 1,
				"groups": [
					3,
					1
				]
			},
			{
				"x": 0.666,
				"y": 0,
				"width": 0.333,
				"height": 1,
				"groups": [
					2,
					1
				]
			}
		]
	}
]

Which results in the following (apparently) working choices in the UI

My question is, are the groups correct? That's the thing I am struggling with most. And also; does the ID have to be a specific pattern, or is it free form (for now)?

[domferr]

The idea of a group is to be a unique integer identifier grouping nearby tiles. So, for example in your split-half layout, there are two tiles nearby and they are part of the same group, let's say group id 1. So both tiles should have only groups: [1].
There isn't a particular nomenclature for the group id. What it is important is that it is an integer.

The other layout should have two groups, let's say 1 and 2: the left tile is grouped with the center tile (let's say group 1), while the right tile is grouped with the center tile as well (let's say group 2). For transitivity, the center tile is part of two groups, 1 and 2.

The reason behind groups is that the layout editor needs such information to place the sliders and allow editing nearby tiles. The other components of Tiling Shell doesn't need the groups to work! In other words, if tiles are part of the same group, increasing or decreasing the width or height of one tile must decrease or increase the width or height of all the other tiles.

One thing that I forgot to mention before: to ensure that the rightmost tile ends with the screen length, its X coordinate plus its width value must be equal to 1. The same applies for the height of course. In your example you may decide that the center tile is 0.334 width and that the rightmost tile starts at X equal to 0.334 with a width of 0.666

(Sorry I'm replying from my smartphone, hope my answer is clear ahahah)

[sebastiaanfranken]

The idea of a group is to be a unique integer identifier grouping nearby tiles. So, for example in your split-half layout, there are two tiles nearby and they are part of the same group, let's say group id 1. So both tiles should have only groups: [1].
There isn't a particular nomenclature for the group id. What it is important is that it is an integer.

The other layout should have two groups, let's say 1 and 2: the left tile is grouped with the center tile (let's say group 1), while the right tile is grouped with the center tile as well (let's say group 2). For transitivity, the center tile is part of two groups, 1 and 2.

The reason behind groups is that the layout editor needs such information to place the sliders and allow editing nearby tiles. The other components of Tiling Shell doesn't need the groups to work! In other words, if tiles are part of the same group, increasing or decreasing the width or height of one tile must decrease or increase the width or height of all the other tiles.

I'm still having a hard time wrapping my head around this. For me it's not clear how a group gets assigned to a tile. I'm going through the code (thanks to grep -rwi group src/) and so far that's bringing up some nice bits of code for me to go through.

Would it make sense if I said that a group "links" two tiles together in the editor, so that what you do to one gets reflected (when required) in the other as well?

One thing that I forgot to mention before: to ensure that the rightmost tile ends with the screen length, its X coordinate plus its width value must be equal to 1. The same applies for the height of course. In your example you may decide that the center tile is 0.334 width and that the rightmost tile starts at X equal to 0.334 with a width of 0.666

That is a good thing to point out, I'd overlooked that! Adding that to my (quickly growing) markdown file, thanks!

[domferr]

Hey sorry for the late response.

Would it make sense if I said that a group "links" two tiles together in the editor, so that what you do to one gets reflected (when required) in the other as well?

This totally makes sense! This is exactly the one and only reason why the groups exist 😄

[sebastiaanfranken]

Hey sorry for the late response.

No worries

This totally makes sense! This is exactly the one and only reason why the groups exist 😄

Glad that clicked for me! Now the next question is, how does the code determine with tile belongs to which group? That's a bit of a mystery for me. Does that get detemined based on order the tiles are created (and/or read in from the JSON file), or am I missing something? If I can get my head around that that would solve the last large issue I am having, and I can finish a very rough draft of my (growing) doc file..

[domferr]

how does the code determine with tile belongs to which group

@sebastiaanfranken

Let's look at the tiles of the following layout:

{
   "id":"Layout 1",
   "tiles":[
      { // this is the TOP-LEFT
         "x":0,
         "y":0,
         "width":0.22,
         "height":0.5,
         "groups":[
            1,
            2
         ]
      },
      { // this is the BOTTOM-LEFT
         "x":0,
         "y":0.5,
         "width":0.22,
         "height":0.5,
         "groups":[
            1,
            2
         ]
      },
      { // this is the CENTER
         "x":0.22,
         "y":0,
         "width":0.56,
         "height":1,
         "groups":[
            2,
            3
         ]
      },
      { // this is the TOP-RIGHT
         "x":0.78,
         "y":0,
         "width":0.22,
         "height":0.5,
         "groups":[
            3,
            4
         ]
      },
      { // this is the BOTTOM-RIGHT
         "x":0.78,
         "y":0.5,
         "width":0.22,
         "height":0.5,
         "groups":[
            3,
            4
         ]
      }
   ]
}

For example the BOTTOM-RIGHT tile belongs to two groups, group 3 and 4! Reason behind that tile has number 3 and 4 in its list of groups. Tiling Shell reads all the tiles and then understands for each group which tiles belong to.

[sebastiaanfranken]

Heh, I know I asked that already, and you already explained it. For some reason I'm having a very hard time wrapping my head around it though. This for me has not "clicked", yet. If you don't mind I'm going to quote your explanation above in my document so that it's clear for other people. If/when it clicks for me I'll see if it benefits from a rewrite/rephrase